Errors

Error responses include error and message. Some errors also include meta, such as refunded quota details after a post-quota service failure. Treat the error value as the stable machine-readable code.

Error response

Fields

error Machine-readable error code.
message Human-readable explanation.
meta Optional. Bulk and refunded failures may include checks_used, checks_remaining, and checks_refunded.

Error codes

status error meaning what to do usage
400 invalid_json The request body is not valid JSON, or it is valid JSON but not an object where an object payload is required. Send a valid JSON object payload and retry. Rate is consumed after authentication. Checks are not consumed.
400 invalid_payload The request body could not be read. Retry with a valid JSON request body. Rate is consumed after authentication. Checks are not consumed.
400 invalid_request A required field is missing or invalid. For /api/v1/check, send a non-empty email string. For /api/v1/bulk, send a non-empty emails array of strings. Fix the request payload before retrying. Rate is consumed after authentication. Checks are not consumed.
400 bulk_limit_exceeded The emails array contains more than 100 emails. Split the request into batches of 100 emails or fewer. Rate is consumed after authentication. No subset is processed and checks are not consumed.
401 unauthorized The bearer token is missing or invalid. Send Authorization: Bearer YOUR_API_KEY. If the key was rotated, update your integration. No endpoint rate or checks are consumed. Failed authentication may count toward pre-auth throttling.
402 quota_exceeded Not enough checks remain for this request. Stop sending checks until your plan renews, reduce the bulk batch size, or upgrade. Checks are not consumed. The request may still count against the rate limit because rate limiting is checked before quota.
403 access_denied The API key belongs to a user whose plan does not include API access. Upgrade to an API-enabled plan or use an API key from a user with API access. No rate or checks are consumed.
403 bulk_blocked Bulk checks are disabled for this API key. Stop using /api/v1/bulk for this key and contact support if this is unexpected. The /api/v1/check endpoint may still be available if your plan allows it. No rate or checks are consumed.
405 method_not_allowed The endpoint was called with a method other than POST. Send a JSON POST request. No rate or checks are consumed.
413 payload_too_large The request body exceeds the endpoint payload limit. Reduce the request body size. For bulk, keep each request at 100 emails or fewer. Rate is consumed after authentication. Checks are not consumed.
429 rate_limited The API key has exceeded its rolling rate limit for this endpoint. Back off and retry later. Use /api/v1/bulk for high-volume jobs to reduce request count. No checks are consumed.
500 service_unavailable The API could not reserve quota, record quota usage, or complete the email check because of a temporary service problem. Retry with backoff. If this repeats, pause the job and contact support. No checks are consumed if quota was not reserved. If quota was reserved and app work later failed, the response includes meta.checks_refunded and restored meta.checks_remaining when the refund succeeds.

Examples

quota_exceeded

{ "error": "quota_exceeded", "message": "Not enough API quota remains for this request." }

bulk_limit_exceeded

{ "error": "bulk_limit_exceeded", "message": "Bulk requests are limited to 100 emails and are rejected in full when this limit is exceeded." }

service_unavailable

{ "error": "service_unavailable", "message": "Could not complete this request right now.", "meta": { "checks_used": 3, "checks_remaining": 4997, "checks_refunded": 3 } }