error code. Use the code and HTTP
status to decide whether to fix the request, poll a job, or retry with bounded
backoff.
Error matrix
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 inputsafe 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_progress429 rate_limit_exceeded503 country_service_maintenanceorcountry_service_temporarily_unavailable- selected network timeouts and
5xxresponses
- Keep the exact same country, phone array, and idempotency key.
- Honor
Retry-Afterwhen present. Authenticated responses also send IETFRateLimit-Limit,RateLimit-Remaining, andRateLimit-Reset(and the legacyX-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.
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: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.