OrbitsDocs
esc
    Open Orbits
    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:

    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" }
      ]
    }
    FieldWhat it holds
    type, title, statusAlways there. type is about:blank, title the status's name, and status repeats the HTTP status.
    detailWhat went wrong, in words you can show a person. A 500 leaves it out rather than say anything about Orbits' internals.
    request_idThe request's id. Quote it when you ask for help.
    errorsOn a 422: one entry per bad field, {field, message}.
    codeA 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, featureOn 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

    StatusMeaningWhat to do
    400The request is malformed: not JSON, or a parameter of the wrong kind.Fix the request.
    401No token, or the token is wrong, revoked or expired.Check Authorization: Bearer orb_live_…; make a new token if it was revoked or expired.
    402The team's plan doesn't include this.See feature; the team's owner can move it to Pro.
    403You 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.
    404It 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).
    409It 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.
    422Validation failed: errors lists each bad field. Also an Idempotency-Key reused with a different body.Fix each field.
    429Over a rate limit.Wait Retry-After seconds. See Rate limits.
    500Something went wrong on Orbits' side.Retry with backoff and the same Idempotency-Key; if it keeps happening, contact support with the request_id.
    502, 503Something 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.

    Was this page helpful?

    Updated