Docs/api/errors - VerifyEmail.io

HTTP Status Codes

Code	Status	Meaning
200	OK	The request was successful. The response body contains the requested data.
400	Bad Request	The request is malformed or missing required parameters (e.g., no `email` parameter).
401	Unauthorized	The API key is missing, invalid, or expired. Check your `Authorization` header or `apikey` parameter.
429	Too Many Requests	You have exceeded your rate limit. Wait until the time indicated by `X-RateLimit-Reset` before retrying.
500	Internal Server Error	An unexpected error occurred on our end. Retry after a short delay. If it persists, contact support.

Error Response Format

When an error occurs, the API returns a JSON object with the following fields:

Field	Type	Description
`error`	boolean	Always `true` for error responses.
`message`	string	A human-readable description of the error.
`status`	number	The HTTP status code (mirrors the response status).

Example Error Response (400)

{
  "error": true,
  "message": "Missing required parameter: email",
  "status": 400
}

Example Error Response (401)

{
  "error": true,
  "message": "Invalid or missing API key.",
  "status": 401
}

Example Error Response (429)

{
  "error": true,
  "message": "Rate limit exceeded. Please try again later.",
  "status": 429
}

Common Errors and Solutions

Missing required parameter: email 400

You called the email verification endpoint without providing an email or domain parameter.

Fix: Add ?email=user@example.com to your request URL or include it in the POST body.

Invalid or missing API key 401

The API key in your request is incorrect, expired, or not provided.

Fix: Verify your API key in the dashboard. Make sure the Authorization: Bearer header is formatted correctly with no extra spaces or quotes.

Rate limit exceeded 429

You have used all your allotted requests for the current billing period.

Fix: Check the X-RateLimit-Reset header to see when your quota resets. Consider upgrading your plan if you consistently hit the limit.

Internal server error 500

Something went wrong on our servers.

Fix: Wait a few seconds and retry. If the error persists after 2-3 retries, contact support with your request details.

Error Handling Example

JavaScript

async function verifyEmail(email) {

  const response = await fetch(

    `https://verifyemail.io/api/email?email=${encodeURIComponent(email)}`,

    { headers: { 'Authorization': `Bearer ${API_KEY}` } }

  );

  if (!response.ok) {

    const err = await response.json();

    switch (response.status) {

      case 400:

        console.error('Bad request:', err.message);

        break;

      case 401:

        console.error('Auth failed. Check your API key.');

        break;

      case 429:

        const reset = response.headers.get('X-RateLimit-Reset');

        console.error(`Rate limited. Resets at ${new Date(reset * 1000)}`);

        break;

      default:

        console.error('Server error. Retrying...');

    }

    return null;

  }

  return await response.json();

}

Python

import requests

import time

def verify_email(email, api_key, retries=3):

  for attempt in range(retries):

    resp = requests.get(

      "https://verifyemail.io/api/email",

      params={"email": email},

      headers={"Authorization": f"Bearer {api_key}"}

    )

    if resp.status_code == 200:

      return resp.json()

    elif resp.status_code == 429:

      reset = int(resp.headers.get("X-RateLimit-Reset", 0))

      wait = max(reset - int(time.time()), 1)

      print(f"Rate limited. Waiting {wait}s...")

      time.sleep(wait)

    elif resp.status_code == 500:

      time.sleep(2 ** attempt)  # exponential backoff

    else:

      resp.raise_for_status()

  return None