Errors and retries

Error responses use JSON and include an error code. Use the code and HTTP status to decide whether to fix the request, poll a job, or retry with bounded backoff.

{
  "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 is not visible ASCII or is outside the 1–255 character limit.	Fix the key; do not retry unchanged.
`400`	`invalid_body`	JSON, country, or the `phones` array is invalid.	Fix the request; do not retry unchanged.
`400`	`unsupported_country`	The country is not in the current OpenAPI catalog.	Use a cataloged country.
`400`	`too_many_phones`	The batch exceeds the endpoint limit: 10,000 for v1 or 500,000 for v2.	Split the work or submit it to the correct endpoint.
`400`	`phone_too_long`	An input exceeds the 64-character per-string limit.	Clean the input before retrying.
`401`	`invalid_key`	The API key is missing, invalid, or revoked.	Fix the secret; do not retry automatically.
`402`	`subscription_inactive`	The selected country subscription is not active.	Resolve billing before retrying.
`403`	`account_suspended`	The organization is suspended.	Contact DNC LATAM support.
`403`	`activation_incomplete`	Required organization privacy/onboarding setup is incomplete.	Complete onboarding before retrying.
`403`	`country_not_in_plan`	The organization has no entitlement for the selected country.	Add the country or use an entitled country.
`409`	`idempotency_request_in_progress`	The same v1 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.
`409`	`job_result_not_ready`	A v2 job is `queued`, `running`, `failed`, or `cancelled` and has no retrievable result yet.	Honor `Retry-After` when present, read status, and retrieve the result only after `succeeded`.
`410`	`job_expired`	A v2 job did not terminalize before its 24-hour input hard cap.	Treat the job as expired; its quota reservation was released and input cleanup is due or already verified.
`410`	`job_result_expired`	A successful v2 result exceeded its seven-day result TTL.	Treat the result as unavailable; submit a new logical job if appropriate.
`405`	`method_not_allowed`	The resource does not support the requested HTTP method.	Use a method listed in the `Allow` header.
`413`	`payload_too_large`	The raw HTTP body, canonical durable input, or conservative complete-result estimate exceeds 25 MiB; v2 also has an independent 500,000-entry ceiling.	Reduce or split the array.
`429`	`rate_limit_exceeded`	The organization exceeded its configured technical window across its API keys. The safe default is 60 requests per 60 seconds; operator overrides are bounded from 1 to 60,000.	Honor `Retry-After` plus IETF `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset` (legacy `X-RateLimit-*` is still sent).
`429`	`temporarily_blocked`	The source triggered the unknown-route abuse guard.	Stop probing unknown paths and honor `Retry-After`.
`429`	`customer_quota_exceeded`	The country Customer Quota would be exceeded.	Stop retries; inspect `country`, `limit`, `used`, and `requested`.
`503`	`country_service_maintenance`	The selected country is in a known maintenance window.	Wait for `Retry-After` or poll the v2 job according to its status.
`503`	`country_service_temporarily_unavailable`	The selected country cannot produce a complete result temporarily.	Retry v1 with the same key or let v2 retry durably.
`503`	`platform_failure`	An internal DNC LATAM component failed.	Retry cautiously with the same logical request or contact support.
`500`	`internal`	An unexpected error outside the public taxonomy occurred.	Record the non-sensitive `request_id`; retry cautiously or contact support.

No partial success

A Scrub Batch is atomic from the customer’s perspective. If a country service, internal chunk, or validation of a provider response fails, the request or job fails as a whole. The API never labels an input safe when the complete determination was not available. Country service failures and platform failures consume no Customer Quota.

Retry policy

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

409 idempotency_request_in_progress
429 rate_limit_exceeded
503 country_service_maintenance or country_service_temporarily_unavailable
selected network timeouts and 5xx responses

For retries:

Keep the exact same country, phone array, and idempotency key.
Honor Retry-After when present. Authenticated responses also send IETF RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (and the legacy X-RateLimit-* names with the same values).
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.

For v2, retry admission only with the same idempotency key. Once the API returns 202, poll the job instead of creating another job. Country-specific provider retries happen internally and are not exposed as a client contract. For a prepaid country whose paid purchase is still pending_activation, the public API returns 503 country_service_temporarily_unavailable. It never returns pending_activation, registry_capacity_exhausted, a provider balance, or another capacity detail. This is intentionally indistinguishable from another temporary country outage at the public boundary. 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. X-RateLimit-Limit is the effective limit for the organization in that 60-second window. Organizations use the safe default of 60 unless DNC LATAM has configured an operator override between 1 and 60,000 requests per window. The technical window is separate from the country-specific monthly Customer Quota.

Quotas count phone inputs

Monthly Customer Quota counts phone inputs, not HTTP requests. API and panel CSV scrubs share the same country-specific allowance for the organization. Invalid inputs and duplicates count because they are submitted inputs. When a country service, platform, or capacity failure occurs, DNC LATAM releases the reservation and records no consumed Customer Quota.

Getting started

Core concepts

Reliability and privacy

Use with AI

API reference

Error matrix

No partial success

Retry policy

Rate-limit headers

Quotas count phone inputs

​Error matrix

​No partial success

​Retry policy

​Rate-limit headers

​Quotas count phone inputs

Error matrix

No partial success

Retry policy

Rate-limit headers

Quotas count phone inputs