Error format
All errors useapplication/json, but the body shape depends on the endpoint
family. Branch on the HTTP status first. Then read code or result.code when
that field is present.
Status codes
Handle common errors
402 Payment Required
402 Payment Required
Your account does not have enough credits, or an API key has reached its credit
limit.Fix: Add credits on the billing page,
or raise the key’s credit limit. Repeat
lookups of an address you already queried are free during the
6-month free-repeat window.
403 Forbidden
403 Forbidden
Your credential is valid, but your workspace role does not permit this action.Fix: Use a key with a non-
readonly role, or ask a workspace admin.429 Too Many Requests
429 Too Many Requests
You sent requests faster than the endpoint allows.The response carries headers to time your retry:
Fix: Wait
X-Ratelimit-Reset seconds, then retry with exponential backoff.
429 responses don’t include Retry-After. See Rate limits.5xx Server and upstream errors
5xx Server and upstream errors
500 is an unexpected failure. 502, 503, and 504 mean an upstream data
provider failed, is unconfigured, or timed out.Retry safely
For a
429, wait X-Ratelimit-Reset seconds before retrying. The value is a
number of seconds, not a timestamp. 429 responses don’t include Retry-After.
Next steps
- Rate limits: Request limits, windows, and backoff guidance.
- Create API key: Fix 401s: create and manage your API keys.