The response envelope, HTTP status codes, and how to handle errors from the Public API.

Error Handling

Every Atlas Public API response — success or error — is returned as JSON wrapped in a consistent envelope.

Response Envelope

Field	Type	Present when	Description
`success`	boolean	Always	`true` for successful requests, `false` for errors.
`message`	string	Always	Human-readable summary of the result.
`data`	any	Success only	The payload (object or array).
`meta`	object	List endpoints	Pagination info (`total`, `page`, `limit`, `next_cursor`).
`code`	string	Errors only	Machine-readable error code (e.g. `UNAUTHORIZED`).
`errors`	object	Validation errors	Field-level detail (e.g. `{ "type": ["required"] }`).
`traceId`	string	Errors only	Request trace ID — include this when reporting an issue.

HTTP Status Codes

Code	Meaning
`200`	OK — request succeeded.
`400`	Bad Request — malformed parameters (e.g. invalid cursor, page out of range).
`401`	Unauthorized — `X-API-Key` header is missing or empty.
`403`	Forbidden — key is valid but does not have access to the requested resource.
`404`	Not Found — entry, page, or media file does not exist, or belongs to a different workspace.
`429`	Too Many Requests — rate limit exceeded; back off and retry.
`500`	Internal Server Error — something went wrong on Atlas's side.

Example Responses

200 — Success

{
  "success": true,
  "message": "Success",
  "data": { "slug": "getting-started-with-headless-cms", "status": "published" }
}

401 — Missing API key

{
  "success": false,
  "message": "missing X-API-Key header",
  "code": "UNAUTHORIZED",
  "traceId": "req_a1b2c3d4"
}

403 — Key has no access to this content type

{
  "success": false,
  "message": "Access to this content type is not allowed for this API key",
  "code": "FORBIDDEN",
  "traceId": "req_e5f6g7h8"
}

404 — Entry not found

{
  "success": false,
  "message": "entry not found",
  "code": "NOT_FOUND",
  "traceId": "req_i9j0k1l2"
}

Handling Tips

Check success first — don't parse data before confirming the request succeeded.
On 401 — verify the X-API-Key header is present and correct. Rotate the key from the dashboard if you believe it has been compromised.
On 403 — the key exists but lacks access to this content type. Check the key's scope in the dashboard (Settings → API Keys).
On 429 — respect the rate limit with an exponential-backoff retry strategy.
Log the traceId from error responses to speed up debugging and support requests.

Error Handling

Error Handling

Response Envelope

HTTP Status Codes

Example Responses

Handling Tips

On this page