Errors
The error format, every error code, and what your code should do.
Errors use standard HTTP status codes and one JSON shape:
{
"error": {
"code": "invalid_request",
"message": "Input should be less than or equal to 90",
"field": "latitude",
"request_id": "req_6e985a89a166b73ea220",
"retryable": false
}
}Program against code, which is stable. message is for people and may change. field names the input at fault, or is null when no single field is.
| Status | Codes | What to do |
|---|---|---|
| 400 | invalid_request | The body is not valid JSON, the Idempotency-Key is too long, or the key was sent in the URL. Fix the request |
| 401 | invalid_key, expired_key | Check or rotate the key. Do not retry in a loop |
| 402 | payment_required | Your plan's payment is overdue past its grace period. Pay it in the dashboard; sandbox keys keep working |
| 403 | account_suspended | The account is not active. Contact support |
| 404 | not_found | There is no such capability, job or file, or it is not yours |
| 409 | idempotency_conflict | See below |
| 410 | link_expired | A PDF download link has expired. Poll the job for a fresh link |
| 410 | file_expired | The PDF is no longer kept. Create a new PDF job |
| 413 | payload_too_large | Reduce the request size |
| 422 | invalid_request, ambiguous_local_time, unsupported_option, unsupported_language | Fix the input. field names the problem |
| 429 | rate_limited | Wait for Retry-After seconds, then retry |
| 429 | quota_exhausted | No credits left, or a sandbox daily limit was reached. Top up, upgrade or wait for renewal. Retrying will not help |
| 429 | spend_cap_reached | Your opt-in overage has reached the monthly spending cap you set (or this call would pass it). Raise the cap or buy a top-up in Billing, or wait for the next period. Retrying will not help |
| 429 | project_budget_exceeded | The key's project has used its monthly credit budget (or this call would pass it). An owner or admin can raise the budget under Projects; it resets on the 1st of the month (UTC). Retrying will not help |
| 500 | computation_failed | Safe to retry with the same idempotency key |
| 501 | not_yet_available | The capability is in the catalogue but not callable on /v1 yet |
| 502 / 503 | unavailable | Retry with exponential backoff and jitter |
| 504 | deadline_exceeded | The calculation took too long. Retry with backoff |
You are never charged for an error. Failed calls do not use credits.
Idempotency conflicts
409 idempotency_conflict has several causes; the message says which:
- the same
Idempotency-Keywas used with a different body: use a new key; - a request with that key is still in progress:
retryableistrue, so retry shortly with the same key; - the key is more than 24 hours old, or its original response is no longer kept: use a new key.
Retrying safely
Retry only when retryable is true. Use exponential backoff with jitter, and send an idempotency key on every request, so a retry after a network timeout can never charge twice.