Error reference
Every CLARA error is an RFC 9457 problem document whose
type URI points at an entry on this page. Branch on the
code field, and quote the request_id when
something needs investigating.
{
"type": "https://www.clara.city/docs/errors#outside_coverage",
"code": "outside_coverage",
"title": "Outside coverage area",
"status": 422,
"detail": "this location is outside the CLARA service area",
"request_id": "7c1f4c2a-0f3e-4d2b-9a6e-5b8d0c1e2f3a"
}One rule makes the codes easy to reason about: a 403 is always about your key and is fixed by talking to us, never by changing the request. A 404 or 422 is always about the data; your key is fine.
validation_error400
A parameter is missing, malformed or out of range: a
radius outside 5 to 50, an address supplied
together with coordinates, a malformed job id, an unknown
metrics value.
What to do. Fix the request; the detail names the
offending parameter. Retrying without a change returns the same
answer.
forbidden403
The key exists and is valid, but is not entitled to what it asked for: it has been deactivated or has expired, it is not scoped to the city the location falls in, the product is not included, a publishable key was used from an unregistered origin, or a secret key was sent from a browser.
What to do. GET /v1/key shows exactly what the
key can reach; the detail says which check failed. Every
fix goes through us, not through your code: new origin, wider scope,
reactivation.
not_found404
No such resource: an unknown city or scale identifier, a report job that never existed, a report file that has expired after its 30 day retention, or a tile address that does not exist.
What to do. Check the identifier against its index:
GET /v1/cities for cities, GET /v1/scales
for scales, your stored job_id for reports. Expired
report files cannot be recovered; generate a new report.
outside_coverage422
The location is outside every covered area, or the address could not be resolved inside one. The request was fine and the key is fine; CLARA simply has no model there yet.
What to do. Treat it as "not covered yet", never as an error
state, especially in partner UIs. The covered areas are listed at
GET /v1/cities and the coverage
page; boundaries at GET /v1/cities/{city} let you
filter before sending requests.
url_expired401
A signed tile or TileJSON URL outlived its expiry, or its signature is invalid. Typical after a laptop wakes from sleep with an old catalog still loaded.
What to do. Re-fetch the map catalog and swap the URLs; a
fresh catalog always carries valid ones. Never store signed URLs
beyond the catalog's meta.url_expires_utc, and never
construct them yourself.
rate_limited429
The key's per-minute request limit is exceeded. The current limit and
your remaining budget travel on every keyed response in the
X-RateLimit-Limit, X-RateLimit-Remaining
and X-RateLimit-Reset headers.
What to do. Wait the number of seconds in
Retry-After, then retry. If you hit this in normal
operation rather than in a burst, ask us for a higher limit; limits
are per key and adjustable.
quota_exceeded429
The key's daily report quota is used up. The quota is checked before any work starts, so a rejected request costs nothing.
What to do. The quota resets at midnight UTC; retrying earlier
changes nothing. GET /v1/key shows the quota. If you
routinely need more reports per day, talk to us.
upstream_error502
Something behind the API failed: the geocoder or the compute back end returned an error. Your request was well formed and may well succeed on a retry.
What to do. Retry, with a short backoff. If it persists, send
us the request_id; it points straight at the failing
hop.
upstream_timeout504
The compute back end did not respond in time. Most often seen on the first historical request for a new location, which computes a full year of statistics before answering.
What to do. Retry. Work already done is kept, so a retry resumes rather than starting over, and the eventual answer lands in the cache for every request after it.