Handling Atlas Errors

Understand Atlas API error responses including HTTP status codes, error structure, and how to handle authentication, payload, resource, and server errors.

Atlas uses standard HTTP status codes to communicate request outcomes. Generally:

2xx means the request succeeded.
4xx indicates a problem with the request as sent (for example, a missing or invalid parameter, failed validation, or insufficient permissions).
5xx signals an error on Atlas’s side. 5xx errors are uncommon and may be retried with backoff.

Structure of an Atlas Error

Most Atlas errors follow the structure below:

JSON

{
  "requestId": "f006ad7b-096c-4254-8c7e-2d23a55b0b0e",
  "requestTimestamp": "2025-09-04 11:49:40",
  "message": "The given data was invalid.",
  "errors": {},
  "statusCode": 422
}

Field	Type	Description
`requestId`	string	Unique identifier for the request. Include this when contacting support.
`requestTimestamp`	string	Timestamp when the error occurred (UTC).
`message`	string	Description of the error.
`errors`	object	Detailed validation errors or additional error context.
`statusCode`	integer	HTTP status code indicating the error type.

Your integration should always check the HTTP status code first and read the top-level message for a quick summary of the error. Additionally, you can inspect the errors for field-level or contextual details and log the requestId to simplify debugging and support requests.

Important

Errors are deterministic: retrying a 4xx request without changing the input will usually fail again. However, 5xx errors may succeed on retry.

Below are some common error categories and how you can handle them.

Authentication Errors

Authentication-related failures occur when Atlas cannot verify your identity or permissions. It usually fails with a 401 Unauthorized status code and can indicate a missing, malformed, or invalid API key/token.

When you encounter this kind of error, it is important to do the following before retrying the request:

Verify that the correct API key is being used. The key required to authenticate requests is your API key which you can find under Dashboard > Settings > Developer > API Key.
Ensure that the API key is being sent as a header in the format Bearer <API KEY>.

If the techniques above do not work and you still receive the error, contact support to escalate your issues.

Authentication on Atlas

Payload Errors

These are the most common category of errors you can encounter on Atlas. It happens when the payload your are sending in your request does not match the one Atlas is expecting.

Common errors and status codes in this category include:

400 Bad Request – Malformed JSON, missing required fields, or invalid data types.
422 Unprocessable Content – Request is syntactically valid, but one or more fields failed validation rules.

When you encounter this kind of error, it is important to do the following before retrying the request:

Ensure that end-to-end encryption is turned on for your account. You can turn encryption on from Dashboard > Settings > Developer > End-to-end-encryption.
Ensure that you are encrypting your payloads with the right keys.
Cross check your payload with the payload in the API reference or Atlas code examples.

If the techniques above do not work and you still receive the error, contact support to escalate your issues.

Encrypting Atlas Payloads

Resource Errors

These errors occur when the requested resource does not exist or cannot be accessed.

Common errors and status codes in this category include:

404 Not Found: The resource ID does not exist or is not visible to your account.
410 Gone: The resource previously existed but has been permanently removed.

When you encounter this kind of error, it is important to do the following before retrying the request:

Confirm the resource ID is correct.

If the techniques above do not work and you still receive the error, contact support to escalate your issues.

Server Errors

Server errors indicate a failure on Atlas’s side.

Common errors and status codes in this category include:

500 Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout

When you encounter 5xx errors, the only thing you can do is to retry the request with exponential backoff while we fix things on our end.

Note

If your request involves write operations use idempotency keys to avoid applying a change multiple times.

If these errors persists, contact support and include the requestId.

Handling Atlas Errors

On this page