> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fawcos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The error format, every code the API returns, and how to handle them.

The API uses standard HTTP status codes. `2xx` means success, `4xx` means the request could not
be completed as sent, and `5xx` means something went wrong on our side.

## The error object

Every error has the same shape:

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "Invalid request",
    "details": [
      { "location": "body", "path": "purpose", "message": "Required" }
    ]
  }
}
```

| Field | Meaning |
| - | - |
| `code` | A short, stable identifier. **Branch on this.** |
| `message` | A human-readable explanation. It may be reworded, so do not match on it. |
| `details` | Optional extra information. Its shape depends on the code. |

## Request ids

Every response from the API, errors included, carries an `X-Request-Id` header such as
`req_3f9c…`. Quote it when you contact support and we can find the exact request.

## Codes

| HTTP | `code` | What it means | What to do |
| - | - | - | - |
| 400 | `validation_error` | The body, query or path failed validation. `details` lists each problem. | Fix the request. Do not retry unchanged. |
| 401 | `unauthorized` | The key is missing, malformed, unknown, revoked or expired. | Check the `x-api-key` header and that the key is still active. |
| 403 | `live_access_not_approved` | A live key was used, but live access is not approved or is suspended. | Finish [going live](/go-live), or use a test key. |
| 403 | `insufficient_scope` | The key lacks the scope this endpoint needs. `details.required` names it. | Create a key with the scope. See [Permissions](/permissions). |
| 403 | `access_denied` | Your organisation is not active. | Contact FaWCOS support. |
| 404 | `not_found` | No such endpoint or resource. | Check the path and id. |
| 429 | `rate_limited` | A per-minute or daily limit was reached. | Back off and retry. See [Rate limits](/guides/rate-limits). |
| 500 | `internal_error` | Something went wrong on our side. | Retry with backoff. If it persists, send us the request id. |

<Note>
  This list covers the endpoints that are live today. It grows as endpoints are released, and
  each new code is added here first.
</Note>

## Handling errors

* Treat `4xx` as final unless the table says otherwise. Retrying an unchanged request will not help.
* Retry `429` and `5xx` with exponential backoff and jitter.
* A timeout or `5xx` on a request that changes something leaves the outcome uncertain. Check the
  state of the thing you were changing before repeating it.
* Log the `X-Request-Id` of every failed request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.