BillionVerify Get Started Free

API Reference

Status and Error Codes

By BillionVerify Team · Last reviewed

Verification Status

StatusMeaningRecommended Action
validEmail exists and can receive messagesSafe to send
invalidEmail does not exist or cannot receiveRemove from list
unknownDeliverability could not be confirmedRetry later or use caution
riskyOnly on results created before 2026-09-11. Deliverable, but the domain was on an external abuse blocklistRemove from list
disposableTemporary or disposable mailboxUsually remove
catchallDomain accepts all addressesMonitor bounce behavior
roleRole-based mailbox such as info@ or support@Usually deliverable, may engage less

New verifications no longer return risky. The blocklist check behind it was removed on 2026-09-11, and risky never means “retry later”. A check that could not finish is returned as unknown, which is not charged.

Error Codes

Every error response has success: false, a numeric string in code, and the same code in error.code. Branch on code, not on the message text.

CodeHTTP StatusDescription
0200Success
1000500Internal server error
1001400Invalid request format
1002400Invalid parameters
1003429Rate limit exceeded
1004503Service temporarily unavailable
1005504Request timeout
1006413Payload too large
1007503Service temporarily overloaded, retry
2000401Unauthorized
2001401Invalid API key
2002401API key expired
2003401API key disabled
2004403Insufficient permissions
3000402Insufficient credits
3001500Credit system error
3002402Team credit limit reached
3100400Invalid email format
3101404Email not found
3102422Email verification failed
3103400Batch size limit exceeded (more than 50 emails)
3200400Unsupported file format
3201400File exceeds the 20 GB limit
3202500File processing failed
3300404Resource not found
3301410Resource no longer available
4000500Database operation failed
4001500Cache operation failed
4002502External service call failed
4003503Upstream provider unavailable

Retry 429, 503 and 504 responses with backoff. A 429 or 503 can carry a Retry-After header.

Best Practices

1. Keep API Keys Out of Source Code

const apiKey = process.env.BV_API_KEY;

2. Use Batch vs File Endpoints Correctly

Use CaseEndpointLimit
Single real-time verification/verify/single1 email
Small synchronous batch/verify/bulk50 emails
Large asynchronous processing/verify/file20 GB per file, no row limit

3. Prefer Webhooks for File Jobs

Polling is supported, but webhooks are a better fit for long-running file verification workflows.