Error Codes

On failure, check the HTTP status code and message field.

Error Body

Business errors always return a machine-readable code you can branch on programmatically:

{
  "code": "insufficient_balance",
  "message": "Insufficient balance for this submission."
}

Error Code Reference

code	HTTP	Description
`unauthorized`	401	API key missing, invalid, or inactive.
`account_banned`	403	Account suspended. Contact support.
`invalid_realtime_request`	400	Malformed realtime request (e.g. a phone number without a `+` international prefix while `country` is omitted).
`idempotency_key_required`	400	Realtime requests require the `Idempotency-Key` header.
`invalid_idempotency_key`	422	`Idempotency-Key` must be 1–128 characters from letters, digits and `. _ : -`
`idempotency_conflict`	409	The same `Idempotency-Key` was used with a different request payload.
`request_in_progress`	409	An identical realtime request is still being processed. Retry shortly (`Retry-After: 1`).
`empty_input`	422	The uploaded file contains no usable rows.
`product_not_found`	422	The submitted product slug does not exist or is inactive.
`product_mode_not_supported`	422	This endpoint does not accept this product mode (realtime products cannot be used on bulk endpoints).
`invalid_country`	422	The product does not support the submitted country.
`too_few_numbers`	422	The submission is below the product minimum.
`too_many_numbers`	422	The submission exceeds the platform maximum.
`insufficient_balance`	402	Not enough balance to cover this submission. Top up and retry.
`realtime_disabled`	403	Realtime detection is not enabled for this account.
`realtime_rate_limited`	429	Realtime rate limit exceeded. Respect `retry_after`.
`product_pricing_unavailable`	503	Pricing for this product is not configured yet. Contact support.
`detection_capacity_unavailable`	503	No detection capacity available right now. Retry later.
`realtime_route_unavailable`	503	No realtime route available. Retry later.
`realtime_fact_cache_unavailable`	503	A realtime dependency is temporarily unavailable. Retry later.
`realtime_rate_limiter_unavailable`	503	The rate limiter is temporarily unavailable. Retry later.
`internal_error`	500	Unexpected server error. Safe to retry with the same `Idempotency-Key`.