API reference · Using the APIErrors
Errors
Every error is an RFC 9457 problem document with a request id. What each status means, the 422 field list, and the 402 plan answer.
An error answers a 4xx or 5xx status with a problem document (RFC 9457), Content-Type: application/problem+json:
{
"type": "about:blank",
"title": "unprocessable entity",
"status": 422,
"detail": "Validation failed",
"request_id": "9f2c4e1a7b3d4c58",
"errors": [
{ "field": "slug", "message": "slug must be 3-40 lowercase letters, digits or hyphens" }
]
}| Field | What it holds |
|---|---|
type, title, status | Always there. type is about:blank, title the status's name, and status repeats the HTTP status. |
detail | What went wrong, in words you can show a person. A 500 leaves it out rather than say anything about Orbits' internals. |
request_id | The request's id. Quote it when you ask for help. |
errors | On a 422: one entry per bad field, {field, message}. |
code | A stable reason, where one is defined: plan_required on a 402; price_changed and already_pro (409) and billing_unavailable (503) from billing. |
required_plan, feature | On a 402: the plan that includes it (pro) and what is missing (functions, sandboxes, analytics or speed_insights). |
Act on the status and on code where there is one, not on the wording of detail, which can change.
Statuses
| Status | Meaning | What to do |
|---|---|---|
400 | The request is malformed: not JSON, or a parameter of the wrong kind. | Fix the request. |
401 | No token, or the token is wrong, revoked or expired. | Check Authorization: Bearer orb_live_…; make a new token if it was revoked or expired. |
402 | The team's plan doesn't include this. | See feature; the team's owner can move it to Pro. |
403 | You are in the team, but not allowed this: your role, a read token writing, a project-limited token outside its project, something no token may do, or the team requires two-factor and the token's owner has it off. | Read detail. See Authentication. |
404 | It doesn't exist, or you can't see it. The two answer the same on purpose. | Check the slug or id, and which team the token reaches (GET /v1/me). |
409 | It conflicts with the current state: a name already taken, a deployment that can't be cancelled any more, a request with the same Idempotency-Key still running. | Read the current state, then decide. |
422 | Validation failed: errors lists each bad field. Also an Idempotency-Key reused with a different body. | Fix each field. |
429 | Over a rate limit. | Wait Retry-After seconds. See Rate limits. |
500 | Something went wrong on Orbits' side. | Retry with backoff and the same Idempotency-Key; if it keeps happening, contact support with the request_id. |
502, 503 | Something the endpoint needs is unreachable for a moment. | Retry shortly, with backoff. |
Each operation in the reference lists the errors it can answer, with what each means there.
Retrying
Retry 429, 500, 502 and 503, waiting longer each time (and Retry-After on a 429). Retry a POST only with the same Idempotency-Key and body, so the change can't happen twice (Conventions). Don't repeat any other 4xx unchanged: it will fail the same way. The SDKs do all of this for you.