> 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/internal-api/errors.md).

# Errors & status codes

When a request fails, the API returns a consistent JSON error envelope so your connector 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 your integration can branch on.
* `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. When building a connector, log the full envelope so failures are easy to trace back to a request.

## 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 project).                                                           |
| `204`  | No content: the request succeeded with no response body.                                                                    |
| `400`  | Bad request: the request was malformed or failed validation (including a missing or invalid `Idempotency-Key`).             |
| `401`  | Unauthorised: the `Api-key` header is missing, invalid or revoked.                                                          |
| `403`  | Forbidden: your credential cannot access the requested company or resource.                                                 |
| `404`  | Not found: the resource does not exist or is not visible to your key.                                                       |
| `409`  | Conflict: for example, an `Idempotency-Key` reused with a different body, or a duplicate `externalId` for the same company. |
| `422`  | Unprocessable entity: the request was understood but could not be processed.                                                |
| `429`  | Too many requests: a rate limit was exceeded. See [Rate limits](/internal-api/rate-limits.md).                              |