feat: adds rfc9457 details to open-api spec

[vireshnavalli]

Description

Adds common error responses for 4xx and 5xx HTTP status code of all API routes as per RFC 9457

Issues Addressed

Address the issue #153

Change Type

Please select the relevant options:

• Fix (change that resolves an issue)
• New enhancement (change that adds specification content)
• Content edits (change that edits existing content)

Checklist

• I have read the CONTRIBUTING document.
• My changes adhere to the established patterns, and best practices.

[vireshnavalli]

@margo/technical-wg / @margo/development-team - The specification changes to support RFC 9457 error responses ready for review.

[ajcraig]

@vireshnavalli here are some comments based on my initial review.

Suggested restructuring of the RFC 9457 problem catalog

I'd like to suggest three structural changes before merge.

1. Consolidate the 11 files into a single page
Recommend collapsing the 10 stubs into one page, using an anchor per problem type (e.g. #certificate-not-trusted), keeping the registry table at the top. Fewer files, one place to maintain, same information.

RFC note: an anchor URI (.../#certificate-not-trusted) is a valid type URI and still dereferences to human-readable docs, so this stays RFC 9457-conformant.

2. Move it under "Margo Management Interface"
Recommend nesting the page under the Management Interface nav section rather than as a top-level Specification node.

3. Relabel "Problems" → "Problem Types"
RFC 9457's term for a catalog entry is a problem type; "Problems" reads as "things that went wrong." The page H1 is already "Problem Type Catalog," so Problem Types is the accurate nav label.

Follow-on cleanup: update the single type example: (currently line 505, .../specification/problems/invalid-digest-header) so it matches the page's final path/anchor, and update the nav block in mkdocs.yml (remove the top-level Problems node; add the page under Management Interface).

[phil-abb]

It might be good to add some overview content to the API Requirements and Security
page since this is a general overview page containing information about the API.

This might be a good place to put some content explaining that the APIs are using RFC 9457 for error responses to establish the pattern being used by the APIs.

[vireshnavalli]

@vireshnavalli here are some comments based on my initial review.

Suggested restructuring of the RFC 9457 problem catalog

I'd like to suggest three structural changes before merge.

1. Consolidate the 11 files into a single page Recommend collapsing the 10 stubs into one page, using an anchor per problem type (e.g. #certificate-not-trusted), keeping the registry table at the top. Fewer files, one place to maintain, same information.

RFC note: an anchor URI (.../#certificate-not-trusted) is a valid type URI and still dereferences to human-readable docs, so this stays RFC 9457-conformant.

2. Move it under "Margo Management Interface" Recommend nesting the page under the Management Interface nav section rather than as a top-level Specification node.

3. Relabel "Problems" → "Problem Types" RFC 9457's term for a catalog entry is a problem type; "Problems" reads as "things that went wrong." The page H1 is already "Problem Type Catalog," so Problem Types is the accurate nav label.

Follow-on cleanup: update the single type example: (currently line 505, .../specification/problems/invalid-digest-header) so it matches the page's final path/anchor, and update the nav block in mkdocs.yml (remove the top-level Problems node; add the page under Management Interface).

Thanks @ajcraig for your review. I have updated the PR, please have a look.