API Error Reference

Every Emailyze API response includes an HTTP status code. This reference covers every status code you may encounter, the JSON error payload, and how to resolve each.

Error Response Format

All errors return JSON with an error field and, where applicable, a code field:

{
  "error": "Invalid email address format",
  "code": "invalid_email"
}

HTTP Status Codes

400 Bad Request

The request was malformed. Common causes:

| Cause | Error message | Fix | |-------|---------------|-----| | Missing email or domain param | "email or domain parameter is required" | Add ?email=user@example.com to your request | | Invalid email format | "Invalid email address format" | Validate the format before calling the API | | Batch payload exceeds limit | "Too many emails. Maximum is 1000 per request" | Chunk your list into batches of ≤1,000 | | Invalid JSON body | "Invalid JSON" | Ensure Content-Type: application/json and valid JSON |

Example 400 response:

{
  "error": "email or domain parameter is required"
}

401 Unauthorized

Your API key is missing or invalid.

{
  "error": "Invalid or missing API key"
}

Causes & fixes:

Key not sent → Add X-API-Key: YOUR_KEY header to every request
Key revoked → Generate a new key in the [dashboard](/dashboard/apikeys)
Trailing whitespace in key → Trim the key value before using it
Wrong header name → Use X-API-Key (not Authorization: Bearer)

403 Forbidden

Your account or plan does not permit this action.

{
  "error": "Daily request limit exceeded for your plan"
}

Causes:

Daily quota exhausted (see [Rate Limits](/blog/docs/rate-limits))
Account suspended (contact support)
Attempting to access an endpoint not on your plan

404 Not Found

The URL does not exist. Most common cause is a missing trailing slash.

{
  "detail": "Not found."
}

Fix: All Emailyze API endpoints require a trailing slash:

✓ /v1/check/
✗ /v1/check (returns 404)

429 Too Many Requests

You have exceeded the rate limit for your plan.

{
  "error": "Request was throttled. Expected available in 1 second."
}

The response includes a Retry-After header with the number of seconds to wait.

Handling 429s:

import time
import requests

def check_email_with_retry(email, api_key, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.get(
            "https://api.emailyze.dev/v1/check/",
            headers={"X-API-Key": api_key},
            params={"email": email},
        )
        if resp.status_code == 429:
            retry_after = int(resp.headers.get("Retry-After", 2 ** attempt))
            time.sleep(retry_after)
            continue
        resp.raise_for_status()
        return resp.json()
    raise Exception("Max retries exceeded")

See [Rate Limits & Quotas](/blog/docs/rate-limits) for per-plan limits and strategies.

500 Internal Server Error

An unexpected error occurred on Emailyze's servers.

{
  "error": "Internal server error"
}

What to do: 1. Retry the request with exponential backoff (500s are usually transient) 2. Check the [status page](https://emailyze.dev/status) for ongoing incidents 3. Contact support if the error persists

Retry Strategy

Use exponential backoff for 429 and 500 errors. Do not retry 400 or 401 — these are client-side issues that retrying will not fix.

import time

RETRYABLE = {429, 500, 502, 503, 504}

def with_backoff(fn, max_attempts=4):
    for attempt in range(max_attempts):
        result = fn()
        if result.status_code not in RETRYABLE:
            return result
        wait = min(2 ** attempt, 30)  # Cap at 30s
        time.sleep(wait)
    return result  # Return last attempt

Error Codes Reference

| Code | HTTP | Meaning | |------|------|---------| | invalid_email | 400 | Email format is invalid | | missing_param | 400 | Required parameter not provided | | invalid_json | 400 | Request body is not valid JSON | | batch_too_large | 400 | Batch exceeds 1,000 emails | | invalid_api_key | 401 | Key missing, revoked, or malformed | | quota_exceeded | 403 | Daily/monthly quota exhausted | | rate_limited | 429 | Per-second rate limit exceeded | | server_error | 500 | Unexpected internal error |