Reference
Errors
Every error the API returns: the response shape, the numeric error codes, what each one means, and what to change to make the call succeed.
Errors return a non-2xx HTTP status and a JSON body with a stable machine-readable code:
{
"success": false,
"error_code": 1002,
"error": "INVALID_API_KEY",
"message": "The API key provided is not valid."
}| Code | Name | When |
|---|---|---|
| 1001 | MISSING_API_KEY | A /v1 endpoint was called without X-API-Key. |
| 1002 | INVALID_API_KEY | The key is malformed or revoked. |
| 2001 | INVALID_IP | The IP address could not be parsed. |
| 2003 | BATCH_TOO_LARGE | More than 100 items in a batch (1000 for bulk report). |
| 3001 | RATE_LIMIT_KEY | Per-key burst limit hit. Retry shortly. |
| 3002 | RATE_LIMIT_IP | Per-IP burst limit hit on a public endpoint. |
HTTP status matches the class: 400 for validation, 401 for auth, 429 for rate limits, 5xx for server errors.