Error Handling

Error Response Format

{
  "error": "Geocoding service error",
  "message": "Detailed error description"
}

Status	Meaning	Common Causes
`400`	Bad Request	Missing required fields, invalid parameters
`401`	Unauthorized	Missing `X-API-Key` header
`403`	Forbidden	Invalid/expired API key, domain or IP blocked, endpoint disabled, quota exceeded
`429`	Too Many Requests	Rate limit exceeded (per-minute or per-day)
`500`	Internal Server Error	Provider API failure, unexpected error

Rate limits are enforced per API key:

When rate limited, the response body includes the limit that was exceeded:

{
  "detail": "Rate limit exceeded: 100 requests per minute"
}

Each customer has per-endpoint quotas that reset daily or monthly:

{
  "detail": "Quota exceeded for geocode endpoint"
}

Check your current quota usage via the Usage endpoint.

If a specific endpoint is not enabled for your account:

{
  "detail": "The geocode endpoint is not enabled for your account"
}

Contact your administrator to enable the endpoint.

If the underlying geocoding provider fails, you'll receive a 500 response:

{
  "error": "Geocoding service error",
  "message": "LocationIQ API request failed: 429 Client Error: Too Many Requests"
}

These are transient errors — retry after a short delay.