Errors - Atlas

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.

⌘I