I like to propose a wording within the API design guideline in line with this comment

Not include line 886 (indeed 501 is not a mandatory code in the way like 401, and 403 are) and after line 811 include specific section, in this way:

Special Consideration for 501 code:
• This code can be only documented in an API endpoint under decision and agreement within a given API Subproject.
• Following guidelines to be considered:
o The use of optional endpoints is discouraged in order to have aligned implementations and deployments
o When the API Subproyect concludes the endpoint can be optional and after the evaluation of the approach of API splitting in the case of being and independent resource.

I think it respects the spirit targeted for this code and also refelcts the relevant guidelines derived from TSC.
@rartych, @eric-murray, @hdamker please if you can take a look

@PedroDiez I am fine with not mixing 501 with 401 and 403.

I propose to extend the point starting in line 806 with the special considerations.
Then it would look like this:

• 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

@PedroDiez I am fine with not mixing 501 with 401 and 403.

I propose to extend the point starting in line 806 with the special considerations. Then it would look like this:

• 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

Perfect Rafal!

I propose to extend the point starting in line 806 with the special considerations. Then it would look like this:

Proposed changes have been applied to the PR