Non-Mandatory Error Response Code Documentation

[sachinvodafone]

Hi Team ,

I just need to confirm whether the error responses defined in Section 6.1 are considered non-mandatory, as one of the notes states: "NOTE: The documentation of non-mandatory error statuses defined in section 6.1 depends on the specific considerations and design of the given API."

Regards
Sachin

[PedroDiez]

Hi Sachin,

Yes, in short that's right. Highlighted in bold the context for each of them

Taken below text from Commonalities Spring25
(new commonalities text is in https://github.com/camaraproject/Commonalities/blob/main/documentation/CAMARA-API-Design-Guide.md#31-standardized-use-of-camara-error-responses from Fall25)

NOTE:
The documentation of non-mandatory error statuses defined in section 6.1 depends on the specific considerations and design of the given API.

• Error statuses 400, 404, 409, 422, 429: These error statuses should be documented based on the API design and the functionality involved. Subprojects evaluate the relevance and necessity of including these statuses in API specifications.
• Error statuses 405, 406, 410, 412, 415, and 5xx: These error statuses are not documented by default in the API specification. However, they should be included if there is a relevant use case that justifies their documentation.
  • Special Consideration for error 501 NOT IMPLEMENTED to indicate optional endpoint:
    • The use of optional endpoints is discouraged in order to have aligned implementations
    • Only for exceptions where an optional endpoint can not be avoided and defining it in separate, atomic API is not possible - error status 501 should be documented as a valid response