Errors

Errors use standard HTTP status codes. Failed requests are not billed — you only pay for successful 200 responses.

Status codes

Status	Meaning
`400`	Bad request — unknown provider id, or a missing key on an otherwise-authenticated session.
`401`	Missing or invalid API key.
`402`	Insufficient balance — top up your account. See billing.
`404`	No result found (all providers missed, or an empty index for `/random`).
`429`	Rate limit or daily quota exceeded. Retry after the `Retry-After` header.
`499`	Client closed the request before a provider responded.

Errors return a JSON body with a machine-readable code and a human-readable message:

{
  "code": "NOT_FOUND",
  "message": "No result found for \"SSIS-999\"."
}

When you hit the rate limit, back off using the Retry-After response header (seconds):

if (res.status === 429) {
  const wait = Number(res.headers.get('Retry-After') ?? 1);
  await new Promise((r) => setTimeout(r, wait * 1000));
}