The shape
A refused request carries content-type: application/problem+json and a body with type, title, status and usually detail. Two extension members are always present for older readers: ok: false and reason, the slug of the type. A rate refusal also carries the IETF RateLimit and RateLimit-Policy fields and Retry-After, so backing off needs no prose parsing.
HTTP/1.1 429 Too Many Requests
content-type: application/problem+json
ratelimit: "default";r=0;t=42
ratelimit-policy: "default";q=120;w=60
retry-after: 42
{"type":"https://obeliskgate.com/problems/read-budget-exhausted","title":"Public read budget exhausted","status":429,"detail":"…","ok":false,"reason":"read-budget-exhausted"}Types
| Type | Status | Meaning |
|---|---|---|
rate-limited | 429 | Too many requests This client has exceeded its request budget for the current window. Honour Retry-After; the RateLimit fields carry the remaining budget and reset. |
read-budget-exhausted | 429 | Public read budget exhausted The unauthenticated read budget for this client is spent for the current window. It never locks out; wait for the reset. |
escalated | 429 | Client escalated by abuse controls Repeated abuse signals from this client paused the surface. This is an abuse verdict, not a quota; it clears on its own clock. |
quota-exceeded | 429 | Account quota reached A per-account ceiling (not a rate) has been reached. Retrying will not help; remove or archive something first. |
step-up-required | 403 | Stronger proof required The session's assurance is too weak for this action. Re-authenticate with a passkey and retry. |
cross-origin-cookie-mutation | 403 | Cross-origin cookie mutation refused A cookie-adopting request arrived from another origin. Send it same-origin with the CSRF header. |
not-found | 404 | Not found No such resource, or it is not visible to this caller. |
bad-request | 400 | Malformed request The request body or parameters did not parse or validate. |
unauthorized | 401 | Authentication required No valid session, token or key was presented. |
forbidden | 403 | Forbidden The caller is authenticated but not permitted to do this. |
gate-unwired | 503 | Abuse gate unwired This surface refuses to serve without its limiter. Fail-closed by design. |