Errors
The API uses conventional HTTP response codes to indicate the success or failure of a request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate a problem with the request. Codes in the 5xx range indicate a server error.
The error object
When a request fails, the response body contains a response_status object with details about what went wrong.
response_statusobjectRequiredTop-level error payload returned when a request fails.
response_status.error_codestringOptionalMachine-readable error code (e.g. "NotEmpty", "Unauthorized").
response_status.messagestringOptionalHuman-readable description of what went wrong. Always read this for the specific failure reason.
response_status.errorsarrayOptionalField-level validation errors. Each entry may include error_code, field_name, message, and meta.
response_status.errors[].field_namestringOptionalThe request parameter or property that failed validation.
response_status.errors[].messagestringOptionalHuman-readable detail for this field-level error.
response_status.errors[].metaobjectOptionalOptional key/value context for the error (e.g. PropertyName, PropertyValue).
HTTP status codes
The codes below describe the general meaning of each status. Do not rely on the HTTP status code alone — always read the message field on response_status (and any field-level entries in errors) for the specific reason the request failed.
OK
The request succeeded. The response body contains the requested data.
Created
The resource was successfully created. The response body contains the new resource.
Accepted
The request was accepted for processing but has not yet completed.
No Content
The request succeeded but there is no response body (e.g. after a DELETE).
Bad Request
The request was malformed. A required parameter may be missing or a value is invalid.
Unauthorized
No valid API key was provided. See Authentication.
Payment Required
The request limit for your current product plan has been reached.
Forbidden
The API key does not have permission to access the requested endpoint or resource.
Not Found
The requested resource does not exist. Check the resource_id and try again.
Method Not Allowed
The HTTP method used is not supported for this endpoint.
Unprocessable Entity
The request was well-formed but contained semantic errors, such as an out-of-range value.
Too Many Requests
You have exceeded your request rate limit or unique location cap for the current period.
Internal Server Error
An unexpected error occurred on our end. Try again after a short delay.
Service Unavailable
The service is temporarily unavailable. Retry with exponential back-off.
Rate limits
Rate limits are enforced per API key and vary by subscription plan. When you exceed a limit, the API returns a 429 Too Many Requests response. The response includes headers that tell you when you can retry.
X-RateLimit-LimitThe maximum number of requests permitted in the current window.X-RateLimit-RemainingThe number of requests remaining in the current window.Retry-AfterSeconds to wait before making another request (present on 429 responses).Handling errors
We recommend writing code that gracefully handles all possible error responses. A few guidelines:
Check the HTTP status first
Do not parse the response body before confirming the status code is in the 2xx range.
Retry on 5xx and 429
Server errors and rate-limit responses are transient. Use exponential back-off with jitter.
Do not retry on 4xx
Client errors (except 429) indicate a problem with your request that will not resolve itself.
Log the message field
response_status.message (and any field-level messages in response_status.errors) contains plain-English explanations that help you debug issues quickly.
Error response examples
What error objects look like
{
"response_status": {
"message": "'latitude' must not be empty.",
"errors": [
{
"field_name": "Latitude",
"message": "'latitude' must not be empty."
},
{
"field_name": "Longitude",
"message": "'longitude' must not be empty."
}
]
}
}