Updated November 13, 2026
Errors
Errors use standard HTTP statuses and a JSON body with a stable code. An invalid email address is a result, not an error.
Error shape
HTTP/1.1 402 Payment Required
{
"error": {
"code": "insufficient_credits",
"message": "This account has 0 credits. Top up at https://app.mailvet.app/billing",
"request_id": "req_01JDA2W1"
}
}Error codes
| HTTP | code | Meaning | Retry? |
|---|---|---|---|
| 400 | invalid_request | A required parameter is missing or malformed. | No, fix the request |
| 401 | unauthorized | Missing, revoked or mistyped API key. | No |
| 402 | insufficient_credits | The account is out of credits. | After topping up |
| 404 | not_found | No verification or bulk job with that id on this account. | No |
| 413 | file_too_large | The bulk file is over 1,000,000 rows or 100 MB. | Split the file |
| 429 | rate_limited | Over the per-second limit. | Yes, after Retry-After |
| 500 | internal_error | Something broke on our side. | Yes, with backoff |
| 503 | unavailable | Temporarily overloaded or in maintenance. | Yes, with backoff |
Invalid addresses are results
GET /v1/verify?email=not-an-email returns HTTP 200 with result: "undeliverable" and reason: "invalid_syntax", free of charge. Errors are only for problems with the request itself.