Errors

Unified error envelope and the full error-code catalog.

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)

code	HTTP status	Meaning
INVALID_API_KEY	401	Missing, malformed, or unrecognized API key
KEY_REVOKED	403	The API key has been revoked
KEY_LOCKED	403	The API key is temporarily locked
CUSTOMER_INACTIVE	403	Your account is currently disabled
FORBIDDEN_SCOPE	403	Your key is valid but lacks the scope required for this endpoint

Validation (400)

code	HTTP status	Meaning
VALIDATION_ERROR	400	Request 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_CURSOR	400	The cursor value is malformed, expired-format, or has been tampered with — see Pagination

Not found (404)

code	HTTP status	Meaning
NOT_FOUND	404	The 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)

code	HTTP status	Meaning
RATE_LIMIT_EXCEEDED	429	You exceeded your tier’s requests-per-minute, requests-per-day, or aggregation-per-minute limit
INFRASTRUCTURE_LIMIT_EXCEEDED	429	An unlimited-tier key hit the platform-wide infrastructure ceiling
QUOTA_EXHAUSTED	429	Your 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)

code	HTTP status	Meaning
INTERNAL_ERROR	500	An unexpected server-side error occurred. Safe to retry with backoff; include request_id when contacting support.
UPSTREAM_UNAVAILABLE	503	The 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

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