REF
Authentication, Errors & Rate Limits
Applies to every /v1/api/ endpoint
Description: Every endpoint requires a Bearer token in the
Status codes you may receive:
Authorization header: Authorization: Bearer <YOUR_TOKEN>. Requests without a valid token get a 401.Status codes you may receive:
200 OK— success (synchronous endpoints).202 Accepted— async job accepted and queued (e.g. Lead Builder execute).400 Bad Request— malformed body, missing/invalid parameter, or a column named in your request is not present in the uploaded data.401 Unauthorized— missing, malformed, or invalid/expired Bearer token.402 Payment Required— insufficient credits for the requested work.403 Forbidden— account suspended (unpaid invoices or API access disabled), or you tried to access a resource that belongs to another account.404 Not Found— the resource ID does not exist (or is not yours — unknown and cross-account IDs both return 404 to prevent ID enumeration).405 Method Not Allowed— wrong HTTP method for the route.409 Conflict— the resource is not ready yet (e.g. reading rows of a lead list that is still processing).429 Too Many Requests— a rate limit was exceeded. Back off and retry; the response body includes how many requests were counted in the window.500 Internal Server Error— an unexpected error. Retry; if it persists, contact support.502/503— the request couldn't be completed right away due to a temporary service delay. This usually resolves on its own. If it persists, contact support.
- Batch Trace & APN Batch Trace — 10 submissions per 5 minutes.
- Instant Trace, APN Instant Lookup & Lead Builder Lookup — 500 lookups per minute (shared counter).
- DNC Scrub — 10 scrubs per 5 minutes.
- DNC Instant Lookup — 30 lookups per minute.
- Fetch all Queues — 1 request per 20 seconds.
- Lead Builder Preview — 500 previews per hour.
- Lead Builder Execute — 10 lists per hour and 50 per day.
- Address Autocomplete — 30 requests per minute.
Headers
Authorization=Bearer <YOUR_TOKEN>
401 Unauthorized — missing or invalid token
{
"detail": "Authentication credentials were not provided."
}400 Bad Request — field validation (detail is a field→messages map)
{
"address": [
"This field is required."
],
"state": [
"This field is required."
]
}402 Payment Required — insufficient credits
// When the account cannot use monthly billing
{
"error": "Insufficient credits. Instant trace requires 5 credits per lookup. You have 0 credits."
}
// When credits are short and no payment method is on file
{
"error": "Insufficient credits. Instant trace requires 5 credits per lookup. Please add credits or a payment method."
}403 Forbidden — account suspended
// Unpaid invoices
{
"error": "Your account has been temporarily suspended due to unpaid invoices. Please contact [email protected] to resolve outstanding payments."
}
// API access disabled for this account
{
"error": "api_disabled",
"detail": "Your API access has been suspended. Please contact support at [email protected].",
"status": 403
}404 Not Found — unknown or cross-account resource ID
{
"error": "No Queue Found with ID 123"
}429 Too Many Requests — rate limited
// Most endpoints — includes the count seen in the window
{
"status": 429,
"error": "Rate limit exceeded. Max 500 lookups per minute.",
"lookups_in_window": 500
}
// Fetch all Queues (20-second throttle)
{
"error": "Rate limit exceeded. Retry in intervals of 20 seconds.",
"retry_in": "3 seconds"
}