# Errors and Response Codes

> Docs index for AI agents: [https://mailvalid.io/llms.txt](https://mailvalid.io/llms.txt). Every docs page is also available as Markdown: add `.md` to 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

```json
{
  "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](https://mailvalid.io/support).