Skip to main content

​
Error envelope

Every error response — regardless of status code — has the same shape: 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Either domains or logins must be provided",
    "request_id": "req_01HZXK3Q7N8YV6F3M2P9JABCDE"
  }
}
  • code — a stable, machine-readable string. Branch your error handling on this, not on message.
  • message — human-readable detail. May change wording over time; don’t parse it.
  • request_id — include this when contacting support.

​
Error code catalog

​
Authentication & authorization (401 / 403)

codeHTTP statusMeaning
INVALID_API_KEY401Missing, malformed, or unrecognized API key
KEY_REVOKED403The API key has been revoked
KEY_LOCKED403The API key is temporarily locked
CUSTOMER_INACTIVE403Your account is currently disabled
FORBIDDEN_SCOPE403Your key is valid but lacks the scope required for this endpoint

​
Validation (400)

codeHTTP statusMeaning
VALIDATION_ERROR400Request body failed schema or cross-field validation (e.g. a required “at least one of” filter is missing, an array exceeds its max length, an enum value is invalid)
INVALID_CURSOR400The cursor value is malformed, expired-format, or has been tampered with — see Pagination

​
Not found (404)

codeHTTP statusMeaning
NOT_FOUND404The requested resource doesn’t exist — e.g. victim_id/log_victim_id could not be resolved, or an unknown sub value was requested on /v1/victims/{victim_id}/{sub}

​
Rate limiting (429)

codeHTTP statusMeaning
RATE_LIMIT_EXCEEDED429You exceeded your tier’s requests-per-minute, requests-per-day, or aggregation-per-minute limit
INFRASTRUCTURE_LIMIT_EXCEEDED429An unlimited-tier key hit the platform-wide infrastructure ceiling
QUOTA_EXHAUSTED429Your daily cost-unit budget is fully consumed
All 429 responses include a Retry-After header (seconds). See Rate Limits & Tiers for the full breakdown and response headers.

​
Server errors (500 / 503)

codeHTTP statusMeaning
INTERNAL_ERROR500An unexpected server-side error occurred. Safe to retry with backoff; include request_id when contacting support.
UPSTREAM_UNAVAILABLE503The API is temporarily in maintenance mode

​
Validation error examples

VALIDATION_ERROR covers many distinct cross-field rules across endpoints — each endpoint’s reference page documents the rules specific to it. Common examples:
filter missing
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Either domains or logins must be provided",
    "request_id": "req_01HZXK3Q7N8YV6F3M2P9JABCDE"
  }
}
array length exceeded
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "domains: list has 120 items, max 100",
    "request_id": "req_01HZXK3Q7N8YV6F3M2P9JABCDE"
  }
}

​
Retrying

StatusRetry guidance
400Don’t retry without fixing the request — retries will fail identically
401 / 403Don’t retry without fixing credentials/scope
404Don’t retry — the resource doesn’t exist
429Retry after Retry-After seconds
500Safe to retry with exponential backoff
503Retry after a short delay — the API is in maintenance mode