Errors

Atlas returns a shared error envelope so integrations can handle failures consistently.

Atlas does not wrap successful responses in a generic status/message/data envelope.

successful reads return resource-shaped JSON
list endpoints return list-shaped JSON
errors always return the shared envelope below

Error envelope

{
  "error": {
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "request_id": "req_01JABCXYZ123",
    "details": null
  }
}

Fields

Field	Type	Meaning
`error.type`	string	Broad error class
`error.code`	string	Stable application code for programmatic handling
`error.message`	string	Human-readable message
`error.request_id`	string	Request correlation ID for support and debugging
`error.details`	object or array or `null`	Optional structured context

Common status codes

Status	Meaning	Typical cause
`400`	Bad Request	malformed request shape or unsupported parameters
`401`	Unauthorized	missing, invalid, expired, revoked, or wrong-environment key
`403`	Forbidden	organization inactive or action not allowed
`404`	Not Found	company, filing, or other resource does not exist
`409`	Conflict	duplicate create attempt or idempotency key reused with a different payload
`422`	Unprocessable Entity	validation failure
`429`	Too Many Requests	rate limit exceeded
`500`	Internal Server Error	unexpected Atlas error

Example: unauthorized

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is invalid for this environment.",
    "request_id": "req_01JABCXYZ124",
    "details": null
  }
}

Example: validation failure

{
  "error": {
    "type": "validation_error",
    "code": "invalid_request",
    "message": "One or more request parameters are invalid.",
    "request_id": "req_01JABCXYZ125",
    "details": [
      {
        "field": "cursor",
        "message": "cursor must be a valid opaque pagination token"
      }
    ]
  }
}

Example: rate limited

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded for the current window.",
    "request_id": "req_01JABCXYZ126",
    "details": {
      "retry_after": 60
    }
  }
}

Headers worth handling

When Atlas rate limits a request, integrations should check:

Retry-After
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset