Errors

Understand the error response format and common status codes returned by the API.

Error Format

All API errors return a consistent JSON object containing a single error field with a descriptive message.

Error Response

{
  "error": "Detailed error message explaining what went wrong."
}

HTTP Status Codes

400Bad Request

The request was invalid or cannot be otherwise served. This usually means a missing required parameter or a validation error (e.g., invalid date format).

401Unauthorized

Authentication failed. Ensure your API key is provided correctly in the Authorization header.

404Not Found

The requested resource (e.g., a specific job ID) or endpoint does not exist.

429Too Many Requests

Two distinct limits can produce a 429, and they need different handling — check the error message to tell them apart. A per-second rate limit ("Too many requests. Please slow down and retry.") clears within a second or two, so a short wait and retry is enough. A monthly quota limit ("Monthly request limit of X reached...") will not clear by waiting — retrying wastes requests; stop and upgrade your plan or wait for the next billing cycle instead.

500Internal Server Error

Something went wrong on our end. We've been notified and are looking into it.

Rate Limit Headers

Successful responses and per-second-limit 429s include rate limit headers, so you can track your usage proactively instead of waiting for a 429. They're absent on a monthly-quota 429 and on a 403 (tier doesn't allow API access) — those are rejected before the per-second bucket is even checked.

Response Headers

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 3
X-RateLimit-Type: list

X-RateLimit-Limit and X-RateLimit-Remaining describe the per-second bucket for the request type (X-RateLimit-Type: list, detail, or geo) — not the monthly quota, which isn't exposed via headers. There is no Retry-After header; since the per-second bucket resets every second, a short fixed wait before retrying is sufficient.

Rate Limiting

Rate limits are applied per API key and reset every second. Watch X-RateLimit-Remaining to stay ahead of a 429 rather than reacting to one. If you are experiencing issues, please contact support.