# HTTP API errors

How the BuildBase HTTP API answers success and failure - the bodies, the HTTP statuses, the code field to branch on, and which requests are safe to retry.

## In short

Every answer has a **status**, a three-digit number: 2xx means it worked, 4xx means something in the request needs changing, 5xx means BuildBase could not finish it. A failed answer also carries a sentence, `message`, that you can show a person, and often a `code`, a fixed word your program can check. Branch on the `code` and the status, never on the wording of the message.

## What a success looks like

A success is `200` (or `201` for some creates) with a JSON body. Most routes answer the object or the list itself:

```json
[{ "_id": "665f1c2e9b1d4a0012ab34cd", "name": "Acme" }]
```

Some answer in an envelope, `{ "success": true, "data": ... }`. Each route keeps the shape it has ([Versioning and changes](/http-api/versioning-and-changes)). A few older routes answer `200` with `"success": false` and a `message` for a refusal: treat `success: false` as a failure whatever the status, as the SDK does.

## What a failure looks like

| Status | When                                                                                                                                                                   | Body                                                                                                                    |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `400`  | A field failed validation, or an id in the path is not a valid id                                                                                                      | `{ "error": true, "path": "<field>", "message": "..." }`                                                                |
| `401`  | The credential is missing, mistyped, expired or revoked. On the organization API, also a key or member whose role has no grant for the route's `x-permission`          | The text `Unauthorized`, or JSON with a `code` where the gate says why, such as `session_ended`                         |
| `402`  | The organization's plan does not cover this                                                                                                                            | `code`: `NO_ACTIVE_PLAN`, `FEATURE_NOT_IN_PLAN`, `PLAN_LIMIT_REACHED` (with `limit` and `current`) or `QUOTA_EXHAUSTED` |
| `403`  | Signed in, but not allowed: a workspace role without the permission, a blocked account, a change that needs a fresh sign-in (`reauth_required`)                        | JSON with `message`, and a `code` where one applies                                                                     |
| `404`  | The id names nothing in this organization or environment, or no route has this path                                                                                    | `{ "error": true, "message": "..." }`; an unknown path answers the text `Not Found`                                     |
| `409`  | It clashes with what exists: a duplicate, a hold no longer open, a request with the same `Idempotency-Key` still running                                               | JSON with `message`, often a `code`                                                                                     |
| `422`  | An `Idempotency-Key` reused for a different request                                                                                                                    | `code`: `IDEMPOTENCY_KEY_REUSED`                                                                                        |
| `429`  | A [rate limit](/http-api/rate-limits) was reached                                                                                                                      | `{ "success": false, "message": "...", "reason": "rate_limited", "retryAfter": 12 }`                                    |
| `500`  | An unexpected failure                                                                                                                                                  | `{ "error": true, "code": "server_error", "message": "Internal server error", "requestId": "..." }`                     |
| `503`  | A failure the route caught (`code: server_error`), or a service it needs is briefly down (`code: temporarily_unavailable`, with `Retry-After` and `retryAfterSeconds`) | JSON with `code` and `message`                                                                                          |

OAuth endpoints answer in OAuth's own shape, `{ "error": "invalid_grant", "error_description": "..." }` ([OAuth endpoints](/authentication/oauth-endpoints)).

A refusal with a code, from the token exchange:

```json
{
  "success": false,
  "code": "impersonation_not_allowed",
  "message": "This API key may not create a session for another user. Issue the key with an owner or admin role, or omit userId to create a session for the key's own user."
}
```

Every `code`, with its status and what to do, is listed in [Error codes](/reference/error-codes).

## Read an error in code

```python title="read_error.py"
import requests

res = requests.get(
    "https://api.console.buildbase.app/api/v1/public/workspaces",
    headers={"x-session-id": session_id},
    timeout=30,
)
if res.ok:
    workspaces = res.json()
else:
    body = res.json() if "json" in res.headers.get("content-type", "") else {}
    print(res.status_code, body.get("code"), body.get("message") or res.text)
    print("request id:", res.headers.get("x-request-id"))
```

## Quote the request id

Every response carries an `x-request-id` header, and a `500` repeats it in the body as `requestId`. Include it when you contact support@buildbase.app: it names the one request in BuildBase's logs.

## When a retry is safe

| You got                                                      | Retry?                                                                                                                        |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `429`                                                        | Yes, after the seconds in `Retry-After` (or the body's `retryAfter`)                                                          |
| `503` with `temporarily_unavailable`                         | Yes, after `Retry-After`                                                                                                      |
| `409` `IDEMPOTENCY_IN_PROGRESS`                              | Yes, shortly, with the same `Idempotency-Key`                                                                                 |
| A timeout, a dropped connection, `500`, `503` `server_error` | A `GET` yes. A write only with the same [`Idempotency-Key`](/http-api/idempotency), or after reading back whether it happened |
| `400`, `401`, `402`, `403`, `404`, `422`                     | No: the same request gets the same answer. Change the request or the credential first                                         |

Back off between attempts: wait 1 second, then 2, then 4, and stop after a few tries. A write that took effect but whose answer was lost is the case `Idempotency-Key` exists for.

## Next steps

- [Error codes](/reference/error-codes) - every `code`, its status and its remedy.
- [Idempotent requests](/http-api/idempotency) - retry a payment or a refund without doing it twice.
- [Rate limits](/http-api/rate-limits) - the limits behind a `429`.
