Errors and Response Codes
Docs index for AI agents: https://mailvalid.io/llms.txt. Every docs page is also available as Markdown: add
.mdto its URL.
The MailValid API uses standard HTTP status codes and returns every error in the same format.
HTTP response codes
| Code | Status | Description |
|---|---|---|
| 200 | OK | Request successful |
| 201 | Created | Resource created (bulk job submitted) |
| 400 | Bad Request | Invalid request format or parameters |
| 401 | Unauthorized | Missing or invalid API key |
| 402 | Payment Required | Insufficient credits |
| 404 | Not Found | Resource not found |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Server Error | Internal server error |
Error response format
{
"detail": "Error message describing what went wrong"
}
Common errors
| Error | Code | Solution |
|---|---|---|
| Invalid API key | 401 | Check your API key is correct and active |
| Insufficient credits | 402 | Purchase more credits from your dashboard |
| Rate limit exceeded | 429 | Wait for the Retry-After period |
| Invalid email format | 422 | Check the email address format |
| Bulk job too large | 400 | Maximum 10,000 emails per request |
Need help?
Contact MailValid support.