Errors
The IPAbuse API uses standard HTTP status codes. Error responses include an error field and may include details. The request ID, when available, is returned in the X-Request-ID response header:
{
"error": "Unauthorized",
"details": "Missing X-API-Key header"
}Error codes
| Code | Name | Description |
|---|---|---|
| 400 | Bad Request | The request body or query parameters are invalid. Check the error message for details. |
| 401 | Unauthorized | Missing or invalid API key / JWT token. Verify your X-API-Key or Authorization header. |
| 403 | Forbidden | Your plan does not include access to this endpoint, or the IP allowlist blocked your request. |
| 404 | Not Found | The requested resource does not exist. Double-check the URL and IDs. |
| 409 | Conflict | The request conflicts with an existing resource. Duplicate-report throttling may instead return 429. |
| 422 | Unprocessable Entity | The payload is structurally valid JSON but fails domain validation (e.g., invalid IP address format). |
| 429 | Too Many Requests | Rate limit exceeded. Wait for the number of seconds in the Retry-After header before retrying. |
| 500 | Internal Server Error | Something went wrong on our side. If this persists, contact support with the request ID from the response. |
| 503 | Service Unavailable | The API is temporarily unavailable. Retry with exponential back-off. |
Validation errors (400 / 422)
When input validation fails, the details field is an array of field-level messages:
{
"error": "Validation failed",
"details": [
{ "field": "ipAddress", "message": "Must be a valid IPv4 or IPv6 address" },
{ "type": "field", "path": "severity", "msg": "Severity must be between 1 and 10" }
]
}Next steps
- Rate Limits — avoid hitting 429.
- API Reference — try endpoints live.