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

# Errors

> One error envelope across the whole API.

Every Atlas API error — validation, auth, not-found, rate limit, or an
unexpected bug — comes back in a single, predictable shape. Clients can rely on
one envelope everywhere.

## The envelope

```json theme={null}
{
  "code": "validation_error",
  "message": "Validation failed"
}
```

| Field     | Type   | Description                                         |
| --------- | ------ | --------------------------------------------------- |
| `code`    | string | A stable, machine-readable code. Branch on this.    |
| `message` | string | A human-readable description. Display, don't parse. |

<Tip>
  Always branch on `code`, never on `message`. Messages may change for clarity; codes are part of
  the contract.
</Tip>

## Common codes

| HTTP status | `code`             | When                                         |
| ----------- | ------------------ | -------------------------------------------- |
| 400         | `bad_request`      | Malformed request.                           |
| 401         | `unauthorized`     | Missing or invalid credentials.              |
| 403         | `forbidden`        | Authenticated but not allowed.               |
| 404         | `not_found`        | The resource doesn't exist (or isn't yours). |
| 422         | `validation_error` | The request failed schema validation.        |
| 429         | `rate_limited`     | Too many requests; back off and retry.       |
| 500         | `internal_error`   | An unexpected server error.                  |

<Note>
  Unexpected server errors return a generic `internal_error` with no internal details — the
  underlying cause is logged server-side, never leaked to the client.
</Note>

## The MCP surface is different

The [MCP server](/mcp/overview) speaks JSON-RPC 2.0, so its failures stay inside
the JSON-RPC error envelope at HTTP `200` rather than using the REST envelope
above. See [MCP transport](/mcp/transport) for the JSON-RPC error codes.