> ## Documentation Index
> Fetch the complete documentation index at: https://lifters.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Complete reference for Atlas API error codes and how to handle them.

## Error Response Format

All Atlas API errors follow this envelope:

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "data.bet_amount: must be greater than 0",
    "request_id": "req_01J3K4M5N6P7Q8R9"
  }
}
```

| Field        | Description                                                    |
| ------------ | -------------------------------------------------------------- |
| `code`       | Machine-readable error code (use this in error handling logic) |
| `message`    | Human-readable description of the error                        |
| `request_id` | Unique request ID — include this when contacting support       |

## HTTP Status Codes

| Status                      | When                                           | Action                                             |
| --------------------------- | ---------------------------------------------- | -------------------------------------------------- |
| `202 Accepted`              | Event published to Kafka                       | No action needed                                   |
| `207 Multi-Status`          | Partial batch failure                          | Retry failed events                                |
| `400 Bad Request`           | Malformed payload or missing required fields   | Fix payload and retry                              |
| `401 Unauthorized`          | Missing or invalid API key / token             | Check credentials                                  |
| `403 Forbidden`             | Valid auth but insufficient permissions        | Check API key scope                                |
| `404 Not Found`             | Endpoint does not exist                        | Check the URL                                      |
| `422 Unprocessable Entity`  | Payload is valid JSON but fails business rules | Fix the data                                       |
| `429 Too Many Requests`     | Rate limit exceeded                            | Back off and retry                                 |
| `500 Internal Server Error` | Atlas server error                             | Retry with backoff; contact support if persistent  |
| `502 Bad Gateway`           | Kafka publish failure                          | Event routed to DLQ; will be retried automatically |
| `503 Service Unavailable`   | Atlas is temporarily down                      | Retry with backoff                                 |

## Error Codes Reference

### Authentication Errors

| Code              | HTTP | Description                                    | Action                                       |
| ----------------- | ---- | ---------------------------------------------- | -------------------------------------------- |
| `UNAUTHORIZED`    | 401  | API key or token is missing                    | Add `X-API-Key` or `Authorization` header    |
| `INVALID_API_KEY` | 401  | API key format is invalid or key doesn't exist | Check key in Dashboard → Settings → API Keys |
| `EXPIRED_TOKEN`   | 401  | JWT token has expired                          | Re-authenticate to get a new token           |
| `INVALID_TOKEN`   | 401  | JWT token signature is invalid                 | Verify token source; re-authenticate         |
| `FORBIDDEN`       | 403  | API key doesn't have access to this brand      | Check brand\_id matches the key's brand      |

### Validation Errors

| Code                 | HTTP | Description                                        | Action                                                          |
| -------------------- | ---- | -------------------------------------------------- | --------------------------------------------------------------- |
| `VALIDATION_ERROR`   | 400  | One or more required fields are missing or invalid | Check `message` field for the specific field                    |
| `INVALID_EVENT_TYPE` | 400  | `event` value is not supported for this endpoint   | Use a valid event name (see [Glossary](/introduction/glossary)) |
| `INVALID_CURRENCY`   | 422  | Currency code is not a valid ISO 4217 code         | Use standard codes: `BRL`, `USD`, `EUR`                         |
| `INVALID_TIMESTAMP`  | 422  | Timestamp is not valid ISO 8601 format             | Use format: `2026-03-11T14:30:00Z`                              |
| `BATCH_TOO_LARGE`    | 400  | Batch contains more than 500 events                | Split into chunks of ≤ 500                                      |
| `EMPTY_BATCH`        | 400  | Batch `events` array is empty                      | Include at least one event                                      |

### Business Logic Errors

| Code              | HTTP | Description                                      | Action                                           |
| ----------------- | ---- | ------------------------------------------------ | ------------------------------------------------ |
| `BRAND_NOT_FOUND` | 422  | `brand_id` doesn't exist in your organization    | Check brand\_id in Dashboard → Settings → Brands |
| `ORG_NOT_FOUND`   | 422  | `org_id` doesn't match the authenticated account | Verify org\_id is correct                        |
| `DUPLICATE_EVENT` | 422  | Event with this ID was already processed         | Do not resubmit; event was already ingested      |
| `NEGATIVE_AMOUNT` | 422  | A monetary amount field is negative              | All amounts must be `>= 0`                       |

### Infrastructure Errors

| Code                   | HTTP | Description                           | Action                                        |
| ---------------------- | ---- | ------------------------------------- | --------------------------------------------- |
| `KAFKA_PUBLISH_FAILED` | 502  | Failed to publish to Kafka            | Event routed to DLQ — automatic retry pending |
| `SERVICE_UNAVAILABLE`  | 503  | Events API is temporarily unavailable | Retry with exponential backoff                |
| `TIMEOUT`              | 504  | Request timed out                     | Retry; check your timeout configuration       |

## Debugging with `request_id`

Every API response includes a `request_id` (or `X-Request-ID` response header). When contacting support about a specific request, always include this ID:

```bash theme={null}
# Check the response header
curl -v -X POST https://events.atlas.io/api/v1/sport \
  -H "X-API-Key: YOUR_KEY" \
  -d '{ ... }' 2>&1 | grep 'X-Request-ID'

# X-Request-ID: req_01J3K4M5N6P7Q8R9S0T1U2V3W4
```

## Contact Support

If you encounter a `500` or `502` error that persists, contact support with:

1. The `request_id` from the response
2. The full request payload (with API key redacted)
3. The timestamp of the request

→ [support@atlas.io](mailto:support@atlas.io) or [resources/support](/resources/support)