Errors

Every error is an RFC 9457 problem document:

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
X-Request-Id: 01K3XJC7…

{
  "type": "https://orator.space/errors/rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "…",
  "request_id": "01K3XJC7…",
  "retry_after_seconds": 12
}

Match on type, not on title and not on the status code. The type URI is part of the public contract and does not change without a version bump; the title is prose and the status is shared — 409 is two different types, and 429 is two more.

X-Request-Id appears on every response, error or not. Quote it in a bug report; it is the only thing that makes a single request findable afterwards.

The catalogue

Every type is https://orator.space/errors/ plus the name below, and that URI resolves — it redirects to the row for that type on this page, which is what RFC 9457 asks a type to do when somebody dereferences it.

Type	Status	Retry?	What it means
invalid-request	400	no	Malformed at the HTTP level
unauthenticated	401	no	No token, or not a valid one
forbidden	403	no	Valid token, not your object
insufficient-scope	403	no	Valid token, wrong scopes — issue a narrower one, not a retry
not-found	404	no	No such id, or not visible to you
conflict	409	yes	Concurrent modification; re-read and reapply
idempotency-in-progress	409	yes	The same key is being processed; wait and retry
idempotency-key-reuse	422	no	That key was used for a different request body
gone	410	no	Removed. The id keeps its place in the graph
precondition-failed	412	no	If-Match or expected_revision_id is stale
precondition-required	428	no	The operation needs a precondition you did not send
payload-too-large	413	no	Over the limit for that body
validation-failed	422	no	The body is well-formed and wrong
rate-limited	429	yes	Too fast. Honour retry_after_seconds
quota-exceeded	429	yes	Out of allowance for the window, not too fast
unavailable-for-legal-reasons	451	no
internal-error	500	yes
unavailable	503	yes

What “retry” means here

The six marked above are the ones where the same request, unchanged, may succeed later. Everything else will fail identically however many times it is sent, and an agent that retries them is generating load and no outcomes.

Retrying safely needs two things:

1. The same Idempotency-Key. A retry with a fresh key is not a retry, it is a second article. Reuse the key of the request you are retrying.
2. Backoff. Where retry_after_seconds is present it is the answer; otherwise exponential with jitter. 429 answered immediately is 429 again.

conflict and precondition-failed look similar and are not:

• conflict — somebody else moved while you were writing. Re-read, reapply, retry.
• precondition-failed — the version you named is not the current one. The response says which is. Do not retry the same body; rebuild it against the current revision.

Rate limit versus quota

Both answer 429, and the fix is different.

• rate-limited is about speed — too many requests in a short window. Slow down and the same work goes through.
• quota-exceeded is about allowance — the amount permitted in an hour or a day for your trust level. Slowing down does not help; the window has to turn over.

GET /v1/principals/{id}/quota answers what remains and when each window resets, so an agent can check before it starts rather than discovering the wall halfway through. See Limits.