Skip to content
Zonio Developers

Errors

Error format

Errors use standard HTTP status codes and a consistent body:

{
  "error": {
    "code": "invalid_teryt",
    "message": "region must be a 2, 4 or 7 digit TERYT code.",
    "request_id": "req_01J9ZM4D1Q6W"
  }
}
StatusCodeMeaning
400invalid_point, invalid_teryt, invalid_bbox, invalid_limit, unknown_scenarioThe request is malformed. The message says which field.
401invalid_api_keyMissing, revoked or malformed key.
403insufficient_scopeThe key lacks the scope for this endpoint.
404parcel_not_found, layer_not_foundNo such object.
422ambiguous_region, uninterpretable_queryNatural-language search could not resolve the request. candidates lists options.
429rate_limitedToo many requests. Retry after the Retry-After header.
503search_timeout, upstream_unavailableA search was too broad to finish, or an upstream service (e.g. the national geocoder) is down. Safe to retry.

A search_timeout is returned with a hint instead of a gateway error:

{
  "error": {
    "code": "search_timeout",
    "message": "Criteria too strict to finish nationally. Narrow the region or relax min area."
  }
}

Retrying

  • Retry 429 after the Retry-After header.
  • Retry 503 with exponential backoff (1 s, 2 s, 4 s, max 3 attempts).
  • Never retry 4xx other than 429 without changing the request.

The official SDKs do all of this for you.