Errors and rate limits

Every status code, what causes it, and whether it costs you a credit.

Status codes

Code	Meaning	Costs a credit?
`200`	A verdict was produced.	Yes
`400`	Malformed body, or a field failed validation.	No
`401`	Missing, malformed or revoked key.	No
`402`	Out of credits. Top up to continue.	No
`413`	Request body too large.	No
`429`	Rate limited. Honour `Retry-After`.	No
`500`	Our fault. Quote the `request_id`.	No
`503`	A dependency is unavailable. Retry shortly.	No

Error shape

{
  "error": "Invalid request",
  "request_id": "01JCQ8Z3F7XK9M2P",
  "details": [
    { "field": "ip", "message": "Invalid IPv4 address" }
  ]
}

Running out of credits

A 402 carries your current balance so your own monitoring can act on it before customers notice:

{
  "error": "Insufficient credits",
  "period": "2026-08",
  "free_used": 1000,
  "free_limit": 1000,
  "paid_remaining": 0
}

Nothing else breaks: your keys stay valid, and the free allowance refills at the start of the next calendar month, UTC. Auto top-up avoids the situation entirely.

Rate limits

120 requests per minute per key. A 429 includes Retry-After in seconds. Rate limiting is per key, not per account, so one noisy environment cannot starve another.

What fails open

Three subsystems deliberately fail towards serving your request rather than rejecting it:

Metering. If the credit ledger is unreachable, the request is served and the credit is forfeited. One free call is cheaper than a false rejection.
Rate limiting. If the limiter is unreachable, the request is served.
DNS. If an MX lookup fails, the signal scores zero and mx_status is unknown, rather than treating an outage as evidence against your customer.

Detection never fabricates a verdict from an infrastructure failure

This is the guarantee the whole product rests on. A score you cannot trust during an outage is a score you cannot trust.

Retrying safely

Both metered endpoints are pure functions of their input: the same request produces the same verdict. Retrying is always safe, and a retry after a non-2xx costs nothing, because the original call was refunded.