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. Include request_id in any support ticket — we log every request and can trace it end-to-end.

Validation errors (422) additionally include an errors array with per-field details.

MISSING_API_KEY — 401, add the X-API-Key (or X-RapidAPI-Key) header.

INVALID_API_KEY — 401, key value not recognised.

SCOPE_DENIED — 403, your plan doesn't cover this endpoint. Most common on /v1/compliance/* called from Free-tier keys.

RATE_LIMIT_EXCEEDED — 429, daily quota exhausted. See the Rate Limits guide.

VALIDATION_ERROR — 422, request failed Pydantic validation. Check the errors array for field-level details (e.g. too_short, missing, value_error).

JOB_TITLE_NOT_FOUND — 404, the fuzzy matcher couldn't map your job_title to any SOC occupation. Try a broader title or call /v1/jobs/search first to pick an exact match.

LOCATION_NOT_FOUND — 404, the location string didn't resolve to a known US metro (BLS MSA code) or EU country. For the US use the canonical MSA name (e.g. New York-Newark-Jersey City, NY-NJ-PA); for the EU use an ISO 3166-1 alpha-2 country code.

NO_DATA_AVAILABLE — 404, a known job/location pair exists but BLS or Eurostat does not publish data for that combination in the requested year. Try a neighbouring metro or a broader occupation group.

INVALID_COUNTRY — 422, the country path parameter on /v1/compliance/* is not a recognised EU/EEA ISO code.

INSUFFICIENT_EMPLOYEES — 422, /v1/compliance/pay-gap-report needs at least 2 employee records to compute a gap. Aggregate at a higher level.

UPSTREAM_DATA_ERROR — 502, BLS or Eurostat source file is unavailable or malformed. We surface this rather than serving stale data. Retry after a few minutes.

INTERNAL_ERROR — 500, unexpected server error with a request_id. Retry once; if it persists, check https://status.aethar.dev or email [email protected] with the request_id.

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

429, 502, and 500 errors should be retried with exponential backoff (1s, 2s, 4s, 8s, 16s). Give up after 5 attempts and surface the request_id to the caller.