> For the complete documentation index, see [llms.txt](https://docs.adaptria.locaria.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.adaptria.locaria.com/client-api/errors.md).

# Errors & status codes

When a request fails, the API returns a consistent JSON error envelope so you can handle failures programmatically.

## Error envelope

```json
{
  "success": false,
  "error": {
    "message": "The requested resource was not found",
    "code": "NOT_FOUND",
    "details": {}
  }
}
```

* `error` is always present on a failed response.
* `error.message` is a human-readable description, intended for logs and developers.
* `error.code` is a machine-readable code you can branch on in your integration.
* `error.details` is optional and carries additional context when available.

Branch on `error.code` rather than parsing `error.message`, since messages may be refined over time.

## Status codes

The API uses the following HTTP status codes:

| Status | Meaning                                                                                      |
| ------ | -------------------------------------------------------------------------------------------- |
| `200`  | Success: the request completed and a response body is returned.                              |
| `201`  | Created: a new resource was created (for example, a new RFQ).                                |
| `204`  | No content: the request succeeded with no response body.                                     |
| `400`  | Bad request: the request was malformed or failed validation.                                 |
| `401`  | Unauthorised: the `Api-key` header is missing, invalid or revoked.                           |
| `403`  | Forbidden: your credential cannot access the requested resource.                             |
| `404`  | Not found: the resource does not exist or is not visible to your key.                        |
| `409`  | Conflict: for example, a duplicate PO number when creating an RFQ.                           |
| `422`  | Unprocessable entity: the request was understood but could not be processed.                 |
| `429`  | Too many requests: a rate limit was exceeded. See [Rate limits](/client-api/rate-limits.md). |