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.

This page is the argument. The API reference is the detail, kept next to the code rather than next to the marketing.

{
  "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.