Errors

The IPAbuse API uses standard HTTP status codes. All error responses have the same JSON shape:

{
  "error": "Unauthorized",
  "details": "Missing X-API-Key header",
  "requestId": "req_01HXXX..."  // include this when contacting support
}

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	Duplicate resource — e.g., you already reported this IP within the deduplication window (24 h).
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" },
    { "field": "severity", "message": "Must be between 1 and 5" }
  ]
}

Next steps

Rate Limits — avoid hitting 429.
API Reference — try endpoints live.