[PedroDiez]

What type of PR is this?

• enhacement
• documentation

What this PR does / why we need it:

Updates the CAMARA API Design Guide with common criteria for distinguishing business-level outcomes in 2xx responses from 4xx errors.

Clarifies that 2xx covers valid results that may be degraded, temporary, partial, or empty, while 4xx applies to validation, authorization, resource, conflict, or permanent inability failures.

Adds scenarios and decision criteria to promote consistent interpretation across CAMARA initiatives.

Which issue(s) this PR fixes:

Fixes #589

Does this PR introduce a breaking change?

• Yes
• No

Special notes for reviewers:

Changelog input

 Business Level Outcome Scenarios Guidance

Additional documentation

This section can be blank.

docs

[bigludo7]

I’d make the description clearer that the endpoint returned a valid status, even though the underlying service is unavailable:

Service temporarily unavailable: The request was processed successfully but the service cannot be provided at this moment but may be available later; the response includes valuable context for the API consumer (e.g., device temporarily not reachable, but retry advised).

[PedroDiez]

thanks for the comment @bigludo7. Better and clearer scenario

[bigludo7]

Thanks @PedroDiez
Look good for me - just a suggestion for the 200 to make if clearer.

[eric-murray]

Hi @PedroDiez

I'd like clearer guidance on when a 200 OK response can be used when the service is temporarily unavailable rather than a 503 UNAVAILABLE error response. This remains a valid CAMARA error response with description:

Service is not available. Temporary situation usually related to maintenance process in the server side.

Both error responses imply that the API consumer can try again later and it may work then.

The implication is that:

• 200 OK with a business level outcome should be used to explain the error when the request has been processed and the API provider knows they should be able to provide the wanted response, but cannot for some reason
• 503 UNAVAILABLE should be used when the API provider cannot even process the request, meaning that a re-submitted request may result in a different error once the request has been processed

Is that the difference? If so, the description in the PR plus the existing description for the 503 UNAVAILABLE error should be updated to reflect this.

[PedroDiez]

Hi @PedroDiez

I'd like clearer guidance on when a 200 OK response can be used when the service is temporarily unavailable rather than a 503 UNAVAILABLE error response. This remains a valid CAMARA error response with description:

Service is not available. Temporary situation usually related to maintenance process in the server side.

Both error responses imply that the API consumer can try again later and it may work then.

The implication is that:

• 200 OK with a business level outcome should be used to explain the error when the request has been processed and the API provider knows they should be able to provide the wanted response, but cannot for some reason
• 503 UNAVAILABLE should be used when the API provider cannot even process the request, meaning that a re-submitted request may result in a different error once the request has been processed

Is that the difference? If so, the description in the PR plus the existing description for the 503 UNAVAILABLE error should be updated to reflect this.

Agree with it

Hi @PedroDiez

I'd like clearer guidance on when a 200 OK response can be used when the service is temporarily unavailable rather than a 503 UNAVAILABLE error response. This remains a valid CAMARA error response with description:

Service is not available. Temporary situation usually related to maintenance process in the server side.

Both error responses imply that the API consumer can try again later and it may work then.

The implication is that:

• 200 OK with a business level outcome should be used to explain the error when the request has been processed and the API provider knows they should be able to provide the wanted response, but cannot for some reason
• 503 UNAVAILABLE should be used when the API provider cannot even process the request, meaning that a re-submitted request may result in a different error once the request has been processed

Is that the difference? If so, the description in the PR plus the existing description for the 503 UNAVAILABLE error should be updated to reflect this.

Agree with it @eric-murray. I will be updating the PR to reflect this

[PedroDiez]

Please @bigludo7, @eric-murray, if you can take a look about current proposal address your comments

[bigludo7]

Look good to me Pedro !
Thanks