Errors

Every error from the Altuq API — whatever the endpoint — uses one stable JSON envelope, so you can handle failures uniformly.

The error envelope

{
  "error": {
    "code": "rate_limited",
    "message": "rate limit exceeded"
  }
}

error.code — a stable, machine-readable string. Branch on this, not on the message or the HTTP status alone.
error.message — a short, human-readable summary. It is safe to display but may change wording over time; do not parse it.

Error responses never include provider-internal detail or the identity of any upstream data source. The code is the contract.

Status	`code`	Meaning
`400`	`bad_request`	A request parameter was missing or invalid (for example, a required field was absent or a coordinate was out of range). Fix the request and retry.
`401`	`unauthorized`	The API key was missing, malformed, unknown, wrong, or revoked. All cases return the same response; a `WWW-Authenticate: Bearer` header is set. See Authentication.
`404`	`not_found`	The product or endpoint does not exist (for example, an unknown product prefix, or an unknown sub-path under a product).
`405`	`method_not_allowed`	The HTTP method is not supported for this endpoint. The geocoding endpoints, for instance, accept `GET` only.
`429`	`rate_limited`	The key's rate limit was exceeded. A `Retry-After` header gives the whole number of seconds to wait. See Rate limits.
`502`	`bad_gateway`	The upstream product could not fulfil the request (it returned an error or an unreadable response). Retryable.
`503`	`unavailable`	The platform could not reach the state it needs to authenticate or rate-limit the request. The edge fails closed rather than allowing an unmetered call. Retryable.
`504`	`gateway_timeout`	The upstream product did not respond within the time budget. Retryable.

4xx (except 429) are your side — inspect code, fix the request or credentials, and retry only after correcting it.
429 is throttling — honour the Retry-After header and back off. See Rate limits.
5xx and 429 are transient — retry with exponential backoff. A jittered backoff avoids retry storms.

A robust client switches on error.code and treats unknown codes conservatively (retry 5xx, do not retry other 4xx).