Error Handling

All API errors follow a consistent format. Here's how to handle them gracefully.

Error response format

When an error occurs, the API returns a JSON object with this structure:

json

{
  "error": "Validation Error",
  "message": "The email field is required.",
  "status_code": 422
}

Status Code	Error	Cause & Solution
`400`	Bad Request	Malformed JSON or missing required fields. Check your request body.
`401`	Unauthorized	Missing or invalid API key. Check your `Authorization` header.
`402`	Payment Required	Insufficient credits. Purchase more credits or wait for daily limit to reset.
`422`	Validation Error	The email address format is invalid. Check the value you're sending.
`429`	Too Many Requests	Rate limit exceeded. Check the `Retry-After` header and wait.
`500`	Internal Server Error	Something went wrong on our end. Try again in a few seconds. Check status.verimails.com.

json

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key",
  "status_code": 401
}

Fix: Check that your Authorization header is formatted correctly as Bearer YOUR_API_KEY. Verify your key in the dashboard.

json

{
  "error": "Validation Error",
  "message": "The email field must be a valid email address.",
  "status_code": 422
}

Fix: Ensure the email value is a valid email format (e.g., user@example.com). Clean your input before sending.

json

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please slow down.",
  "status_code": 429,
  "retry_after": 15
}

Fix: Wait the number of seconds in retry_after before retrying. See Rate Limits →