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/career/* 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).

OCCUPATION_NOT_FOUND — 404, the fuzzy matcher couldn't resolve the occupation slug or free-text title to an O*NET / SOC entry. Try the canonical slug (e.g. data-scientist) or call /v1/occupations/search first to pick an exact match.

SKILL_NOT_FOUND — 404, the skill slug didn't resolve to an O*NET, ESCO, or Lightcast skill. Try /v1/skills/search to discover the canonical slug.

SOC_CODE_NOT_FOUND — 404, the supplied SOC code is not in the BLS 2018 SOC taxonomy. Check the SOC manual or use a slug-based lookup.

NO_DATA_AVAILABLE — 404, a known occupation exists but the requested data slice (e.g. wages, employment outlook) is not published for that occupation. Try a related occupation or a coarser SOC group.

CAREER_PATH_INFEASIBLE — 422, the requested transition between occupations has zero overlap in the skills graph and cannot be planned automatically. Try a related intermediate occupation.

UPSTREAM_DATA_ERROR — 502, O*NET, ESCO, or Lightcast 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.