Errors

Every non-2xx response uses the same JSON shape:

{
  "error": {
    "code": "UPPER_SNAKE_CODE",
    "message": "Human-readable message.",
    "status": 422,
    "request_id": "c0a8012e-7b2c-4e1a-9b8f-2f4f7d3c1a55",
    "suggestion": "What to do about it.",
    "doc_url": "https://docs.aethar.dev/errors/<slug>"
  }
}

Always check error.code, not the message string — messages may change between versions, codes are stable.

MISSING_API_KEY — 401, add the X-API-Key header.

INVALID_API_KEY — 401, key value not recognised.

SCOPE_DENIED — 403, upgrade your plan or generate a new key.

VALIDATION_ERROR — 422, request body failed Pydantic validation. Check the errors array for field-level details.

UNANONYMIZED_PII_DETECTED — 422, strict-mode PII anonymization found residual identifiers in the /intelligent/parse input. Manually redact and retry.

CONVERSION_FAILED — 400, your input was a well-formed JSON but not a valid EN 16931 invoice.

SCHEMATRON_FAILED — 422, your XML passed XSD schema check but failed Schematron business rules. Read the errors array.

ANONYMIZATION_INTEGRITY_ERROR — 502, the AI parse step returned output that couldn't be cleanly de-anonymized. Retry.

AI_SERVICE_ERROR — 503, upstream AI provider (Anthropic) is unavailable. Retry with exponential backoff.

RATE_LIMIT_EXCEEDED — 429, see Rate Limits guide.

4xx errors other than 429 should NOT be retried — they're client bugs, retrying won't fix them.

429 and 5xx errors should be retried with exponential backoff (1s, 2s, 4s, 8s, 16s). Give up after 5 attempts.