Errors and retries

Error responses use JSON and include an error code. Many also include a human-readable message and structured fields that should drive recovery.

{
  "error": "rate_limit_exceeded",
  "message": "rate limit exceeded",
  "limit": 60,
  "window_seconds": 60,
  "retry_after": 12
}

Error matrix

HTTP	`error`	Meaning	Client action
`400`	`missing_idempotency_key`	The required header is missing.	Generate a new opaque key for the logical request.
`400`	`invalid_idempotency_key`	The key does not meet format requirements.	Use 1–255 visible ASCII characters without spaces.
`400`	`invalid_body`	JSON or the `phones` array is invalid.	Fix the request; do not retry unchanged.
`400`	`unsupported_country`	`country` is not `mx` or `ar`.	Split and send a supported country.
`400`	`too_many_phones`	The batch exceeds the current OpenAPI limit.	Split the work into smaller logical requests with different idempotency keys.
`400`	`phone_too_long`	At least one input exceeds the per-string limit.	Reject or clean that input before retrying.
`401`	`invalid_key`	The API key is missing, invalid, or revoked.	Fix or rotate the secret; do not retry automatically.
`402`	`subscription_inactive`	The Stripe-backed subscription is not active.	Resolve billing before retrying.
`403`	`account_suspended`	The organization is suspended.	Contact DNC LATAM support.
`403`	`country_not_in_plan`	The selected country is not enabled.	Add the country or use an entitled country.
`409`	`idempotency_request_in_progress`	The same logical request is still running.	Respect `Retry-After`; retry the exact payload with the same key.
`409`	`idempotency_key_reused`	The key was used with a different payload.	Generate a new key for the new logical request.
`413`	`payload_too_large`	The HTTP body exceeds the transport limit.	Reduce or split the batch.
`429`	`rate_limit_exceeded`	The organization exceeded 60 requests per 60 seconds across its API keys.	Respect `Retry-After` and rate-limit headers.
`429`	`monthly_quota_exceeded`	The country-specific monthly number allowance is exhausted.	Stop retries; inspect `country`, `limit`, `used`, and `requested`, then change volume in billing if needed.
`429`	`temporarily_blocked`	The source IP triggered unknown-route abuse protection.	Stop probing unknown routes and respect `Retry-After`.
`503`	`capacity_exceeded`	The API is at bounded temporary capacity.	Respect `Retry-After` and retry with bounded backoff.
`500`	`internal`	An unexpected server failure occurred.	Record the non-sensitive `request_id`; retry cautiously or contact support.

Retry policy

Retry only failures that can recover without changing the logical request:

409 idempotency_request_in_progress
429 rate_limit_exceeded
503 capacity_exceeded
selected network timeouts and 5xx responses

For those retries:

Keep the exact same country, phone array, and idempotency key.
Honor Retry-After when present.
Add exponential backoff with jitter when no delay is provided.
Set a bounded attempt count and total deadline.
Never log the phone array or authorization header.

Do not automatically retry validation, entitlement, billing, quota, or idempotency-conflict errors.

Rate-limit headers

A technical rate-limit response can include:

Retry-After: 12
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1780000000

X-RateLimit-Reset is a Unix timestamp.

Quotas count phone inputs

Monthly allowances count summary.total_checked inputs, not HTTP requests. API and CSV scrubs share the same country-specific allowance for the organization. Invalid inputs and duplicates count because they are submitted inputs.

Getting started

Core concepts

Reliability and privacy

Use with AI

API reference

Error matrix

Retry policy

Rate-limit headers

Quotas count phone inputs

​Error matrix

​Retry policy

​Rate-limit headers

​Quotas count phone inputs

Error matrix

Retry policy

Rate-limit headers

Quotas count phone inputs