Error Codes

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

Error Response Format

All Atlas API errors follow this envelope:

{
  "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)
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:

# 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

→ [e-mail] or resources/support