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
{
"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. |
Always branch on code, never on message. Messages may change for clarity; codes are part of
the contract.
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. |
Unexpected server errors return a generic internal_error with no internal details — the
underlying cause is logged server-side, never leaked to the client.
The MCP surface is different
The MCP server 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 for the JSON-RPC error codes. 
