Error Handling

Error Response Format

All Aura API errors return a consistent JSON body:

{
  "error": "Human-readable message",
  "error_code": "machine_readable_code",
  "detail": "Additional context or validation details"
}

HTTP Status Codes

Code	Name	Meaning
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid parameters or request body
401	Unauthorized	Missing, invalid, or expired API key
403	Forbidden	No Authorization header present (wrong auth scheme)
404	Not Found	Resource does not exist
422	Unprocessable Entity	Request schema validation failed — check field types and required fields
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side failure

Common Errors

401 Unauthorized

{
  "error": "Not authenticated",
  "error_code": null,
  "detail": "Not authenticated"
}

Cause: Missing or invalid X-API-KEY header. Fix: Ensure every request includes X-API-KEY: your_key.

---

422 Validation Error

{
  "error": "Validation error",
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Cause: A required field is missing or has the wrong type. Fix: Check the API Reference for the required request schema for that endpoint.

---

404 Not Found

{
  "error": "Not found",
  "error_code": null,
  "detail": "Not found"
}

Cause: The resource ID doesn’t exist or doesn’t belong to your account. Fix: Verify the ID using the corresponding list endpoint first.

---

429 Rate Limited

Back off and retry after the delay indicated in the Retry-After response header. Use exponential backoff for automated clients:

import time

def request_with_retry(fn, max_retries=3):
    for attempt in range(max_retries):
        resp = fn()
        if resp.status_code == 429:
            wait = 2 ** attempt
            time.sleep(wait)
            continue
        return resp
    raise Exception("Max retries exceeded")