nofakemailsnofakemails

Error Codes

Complete reference of all error codes returned by the nofakemails API and how to handle them.

Error Response Format

All error responses follow a consistent JSON structure:

{
  "status": 400,
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}

HTTP Status Codes

400

Bad Request

The request was malformed or contains invalid parameters. Check your request body and parameters.

MISSING_EMAIL

The email parameter is required but was not provided or is empty.

Why this happens: You called the /v1/email/{email} endpoint without providing an email address in the URL path, or the email parameter was empty.

{
  "status": 400,
  "error": "Email address is required",
  "code": "MISSING_EMAIL"
}
INVALID_EMAIL_FORMAT

The provided email address does not conform to RFC 5322 email format.

Why this happens: The email address you provided has invalid syntax. Common issues include missing @ symbol, invalid characters, missing domain, or malformed local part.

{
  "status": 400,
  "error": "The email address is invalid.",
  "code": "INVALID_EMAIL_FORMAT"
}
EMPTY_BATCH

The batch validation request contains no email addresses.

Why this happens: You called the batch endpoint /v1/emails with an empty emails array or the field was missing entirely from the request body.

{
  "success": false,
  "error": {
    "code": "EMPTY_BATCH",
    "message": "Batch must contain at least one email address"
  }
}
BATCH_SIZE_EXCEEDED

The batch contains more emails than the maximum allowed limit.

Why this happens: You attempted to validate more than 64 unique email addresses in a single batch request. Split your emails into multiple batches of 64 or fewer. Enterprise clients can request higher limits.

{
  "success": false,
  "error": {
    "code": "BATCH_SIZE_EXCEEDED",
    "message": "Batch size 100 exceeds maximum allowed (64)",
    "max_allowed": 64,
    "received": 100
  }
}
401

Unauthorized

Authentication failed. Your API key is missing, invalid, or has been revoked. See Authentication for how to properly configure your API key.

INVALID_API_KEY

The provided API key is invalid, expired, or has been revoked.

Why this happens:

  • The X-API-Key header or Authorization: Bearer token is missing
  • The API key was copied incorrectly (check for extra spaces or missing characters)
  • The API key was deleted from your dashboard
  • The API key belongs to a different environment (test vs. production)
  • Your account has been suspended
{
  "status": 401,
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
402

Payment Required

You don't have sufficient usage quota to complete this request.

INSUFFICIENT_USAGE

Your account doesn't have enough remaining usage points for this batch validation.

Why this happens:

  • You've exhausted your monthly quota (Freemium tier: 1,000/month)
  • The batch request requires more points than you have remaining
  • Your billing period hasn't reset yet

Solution: Upgrade to Pro tier for 200,000 validations/month with overage support, or wait for your billing period to reset.

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_USAGE",
    "message": "Insufficient usage points for batch validation",
    "required": 50,
    "remaining": 10
  }
}
429

Too Many Requests

You've exceeded the rate limit for your subscription tier. See Rate Limits for tier-specific limits and the token bucket algorithm.

Rate limiting is enforced per account using a token bucket algorithm.

Why this happens:

  • Freemium tier: More than 1 request per second
  • Pro tier: More than 5 requests per second
  • Multiple API keys under the same account share the same rate limit

Solution: Check the Retry-After header for when to retry. Implement exponential backoff in your code. Upgrade to a higher tier for increased limits.

{
  "status": 429,
  "title": "Too Many Requests",
  "detail": "You have exceeded the rate limit. Please try again in 1 seconds."
}
500

Internal Server Error

An unexpected error occurred on the server while processing your request.

INTERNAL_ERROR

Something went wrong on our end.

Why this happens: This is typically a temporary issue with our infrastructure. It could be caused by DNS lookup failures, database connectivity issues, or other internal problems.

Solution: Retry the request with exponential backoff. If the error persists for more than a few minutes, please contact support.

{
  "status": 500,
  "error": "An error occurred while validating the email",
  "code": "INTERNAL_ERROR"
}
503

Service Unavailable

The service is temporarily unavailable or the request was cancelled.

REQUEST_CANCELLED

The request was cancelled before it could complete.

Why this happens:

  • The client disconnected before the response was sent
  • The request timed out during processing
  • The service is undergoing maintenance
  • A dependent service (like DNS) is temporarily unavailable

Solution: Retry the request after a short delay. This is usually a transient issue.

{
  "status": 503,
  "error": "Request was cancelled",
  "code": "REQUEST_CANCELLED"
}

Error Codes Summary

CodeStatusEndpointDescription
MISSING_EMAIL400SingleEmail parameter is missing
INVALID_EMAIL_FORMAT400SingleEmail format is invalid
EMPTY_BATCH400BatchEmails array is empty
BATCH_SIZE_EXCEEDED400BatchMore than 64 unique emails
INVALID_API_KEY401AllAPI key is invalid or missing
INSUFFICIENT_USAGE402BatchNot enough usage points
INTERNAL_ERROR500AllUnexpected server error
REQUEST_CANCELLED503AllRequest was cancelled or timed out

Handling Errors

Here's a recommended approach for handling API errors in your application:

Retry Strategy

  • 4xx errors (except 429): Do not retry. Fix the request parameters.
  • 429 errors: Retry after the Retry-After header duration.
  • 5xx errors: Retry with exponential backoff (1s, 2s, 4s, max 3 retries).

Next Steps