# 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.                                       |

## Handling Atlas Errors

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.

### 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.

### Payload Errors

These are the most common category of errors you can encounter on Atlas. It happens when the payload you 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.

### 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.

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

If these errors persist, contact support and include the `requestId`.