# 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.

Source: https://docs.orbits.africa/api/errors

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" }
  ]
}
```

| 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](https://docs.orbits.africa/help/support). |
| `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](https://docs.orbits.africa/billing/plans). |
| `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](https://docs.orbits.africa/api/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](https://docs.orbits.africa/api/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](https://docs.orbits.africa/api/conventions)). Don't repeat any other `4xx` unchanged: it will fail the same way. The SDKs do all of this for you.
