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.

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).

NO_GDP_DATA — 404, no GDP data available for the requested country. Check that it's an EU/EEA member.

DATASET_NOT_FOUND — 404, the dataset code is not recognised. Use GET /v1/datasets to list available datasets.

NO_DATA_AVAILABLE — 404, a known country exists but no data is available for the requested parameters. Try a different time range or frequency.

UPSTREAM_DATA_ERROR — 502, Eurostat SDMX API is unavailable or returned malformed data. 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.