Skip to main content
The Extended API returns standard HTTP status codes and a JSON error body for every non-2xx response.

​
Error body shape

{
  "error": {
    "code": "string",
    "message": "string",
    "details": { }
  }
}
FieldTypeDescription
codestringMachine-readable identifier
messagestringHuman-readable summary, safe to show to your users
detailsobjectOptional context — upstream lookup data, validation field map, etc.

​
Status codes

StatusMeaningTypical cause
400 Bad RequestInvalid inputMalformed email, invalid domain, bad payload
401 UnauthorizedMissing or invalid tokenNo Authorization header, expired key
403 ForbiddenAuthenticated but not allowedKey scope insufficient
404 Not FoundResource or record not presentDomain has no DNS record of the requested type
408 Request TimeoutUpstream lookup exceeded timeoutDNS or upstream provider slow — retry once
429 Too Many RequestsRate limited or quota exhaustedHonour Retry-After; check your remaining quota
500 Internal Server ErrorUnexpected platform errorRetry with backoff
503 Service UnavailableTemporary capacity issueRetry with backoff

​
Common error codes

codeWhen it appears
invalid_emailAddress fails syntactic or domain validation
invalid_domainDomain does not resolve or is malformed
dns_lookup_failedDNS query returned an error or timed out
quota_exhaustedDaily or plan-level credit limit reached
provider_errorUpstream delivery provider rejected the operation
timeoutThe upstream lookup did not return within the configured window

​
Quota errors

Validation and AI-scoring endpoints are credit-metered. A 429 with code: "quota_exhausted" includes a details.reset_at timestamp indicating when the quota window resets.

​
Retry guidance

  • Lookups (GET): retry on 5xx, 408, and 429 with exponential backoff.
  • SMS dispatch (POST): include an Idempotency-Key to make retries safe. Do not retry 4xx.