Errors

The APEX error catalog — a consistent JSON envelope with a stable machine-readable code, the full list of estimation and admin codes, the responses that look like errors but aren't, and retry guidance.

APEX errors return a non-2xx status and a consistent JSON envelope. Branch on the code, not on the error text. The shared error conventions are in API conventions; this page is the APEX-specific catalog.

Response format

{
  "error": "human-readable message",
  "code": "MACHINE_READABLE_CODE",
  "message": "additional detail",
  "endpoint": "/api/v1/endpoint"
}

Field	Always present	Description
`error`	yes	Short description of what went wrong.
`code`	yes	Stable machine-readable code — branch on this.
`message`	sometimes	Additional context.
`endpoint`	sometimes	Which endpoint returned the error.
`detail`	sometimes	Validation details (binding errors).

Authentication

HTTP	Code	Meaning
401	`KEY_MISSING`	No `X-API-Key` header.
403	`KEY_INVALID`	Key hash not found, or key revoked.
403	`KEY_VALIDATION_ERROR`	Backend unreachable during validation — denied as a precaution; retry once.

Rate limiting

HTTP	Code	Meaning
429	`RATE_LIMITED`	Per-key minute budget exhausted; honour `Retry-After`. See Rate limiting.

Estimation

HTTP	Code	Meaning
400	`ESTIMATE_BIND_ERROR`	Malformed JSON or missing/invalid fields (see `detail`).
400	`ESTIMATE_INVALID_REQUEST`	Semantically invalid (e.g. `distance_km <= 0`, missing countries).
500	`ESTIMATE_QUERY_ERROR`	Backend failure during estimation; retry with backoff.
400	`BATCH_ESTIMATE_BIND_ERROR`	Batch body malformed (`items` missing, >500, or wrong shape).
500	`BATCH_ESTIMATE_QUERY_ERROR`	Backend failure during batch processing; retry with backoff.
500	`LIST_CORRIDORS_QUERY_ERROR`	Backend failure listing corridors; retry with backoff.

Not errors (but look like them)

INSUFFICIENT_DATA — a 200 OK with zeroed prices and match_level: "none" means no cascade level had enough observations (exact < 3, reverse < 3, postal-prefix < 5, country-pair < 10). Verify country codes are ISO 3166-1 alpha-2 and postal codes are real — but some lanes genuinely have no coverage yet. See Estimate.
Empty analytics responses — analytics endpoints return empty arrays when nothing matches the filters. Widen the period (or use period=all), lower min_quality, or drop the shipment_type filter. Periods anchor to the newest observation, not the wall clock.
Batch items with errors — items fail independently; inspect each result for error vs result.

Retry strategy

429 — wait the Retry-After seconds, then retry.
5xx — exponential backoff (1s, 2s, 4s), give up after three attempts.
Other 4xx — do not retry; fix the request.
403 KEY_VALIDATION_ERROR is the one 4xx worth retrying once — it signals a transient backend problem, not a bad key.