Developers — API

Errors that name the remedy.

RFC 9457 problem details, with a field most APIs do not carry: what to do about it. An error that tells you something failed and not how to proceed has made the failure your problem twice.

{
  "type": "https://rotascale.com/problems/invalid-request",
  "title": "Invalid request",
  "status": 422,
  "detail": "'settle-bot' runs in prod and would refuse actions under this
             authority, but its clearance is unknown.",
  "remedy": "certify the agent against its current configuration"
}

Two things the API refuses on principle

A service principal cannot issue authority: Grants, delegation and enforcement changes are governance acts and belong to a named person over OIDC. An API key gets 403 with the reason spelled out — because "a human authorised this" has to be true, not merely recorded.
A private key never crosses the API: Not on any route, in any direction. The capability is absent from the interface rather than present and forbidden, and a test fails the build if a response model ever grows a field that could carry one.

The OpenAPI document is served from the deployment itself at /api/docs, because it knows which features are on. A copy on this website would drift from the instance you are integrating against, and the drift would be invisible.