Error & Status Codes

Guides

Reference

End Points Overview

Single Email Validation

Bulk Email Validation

Tutorials

Realtime SSE

Credits & Billing

Error & Status Codes

Search Docs…

The API follows a consistent error format across all endpoints.
Every failed request returns:

success: false
Standardized error.code
Human-readable error.message
Optional details and field
Metadata with request ID and timestamp

This page explains all error types, their meanings, and how to handle them correctly.

1. Standard Error Format

Every error returned by the API uses this structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": "Additional context (optional)",
    "field": "email (optional)"
  },
  "metadata": {
    "request_id": "550e8400-e29b-41d4...",
    "processing_time_ms": 1,
    "timestamp": "2025-01-15T10:30:00Z",
    "version": "1.0.0"
  }
}

This structure is consistent across:

Single email validation
Bulk job creation
File upload
Status checks
Credit APIs

2. HTTP Status Codes

Code	Status	Description
200	OK	Request successful
202	Accepted	Bulk job created and queued
400	Bad Request	Invalid payload or parameters
401	Unauthorized	Missing/invalid API key
402	Payment Required	Insufficient credits
403	Forbidden	Access denied to a resource
404	Not Found	Job or resource does not exist
405	Method Not Allowed	Wrong HTTP verb
410	Gone	Bulk results expired (after 7 days)
413	Payload Too Large	File larger than 10MB
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server issue
503	Service Unavailable	System temporarily unavailable

3. Common Error Codes

Below are the most frequent error codes returned by the API.

VALIDATION_FAILED (400)

Invalid email format or invalid request body.

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid email format",
    "field": "email"
  }
}

UNAUTHORIZED (401)

Invalid or missing API key.

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key"
  }
}

INSUFFICIENT_CREDITS (402)

Credits exhausted.

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits. Please purchase more credits to continue."
  }
}

FORBIDDEN (403)

User does not own the resource (job, results, etc.).

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have access to this resource"
  }
}

JOB_NOT_FOUND (404)

Bulk job ID does not exist or belongs to another user.

{
  "success": false,
  "error": {
    "code": "JOB_NOT_FOUND",
    "message": "Job not found"
  }
}

INVALID_FILE_FORMAT (400)

File is not CSV, JSON, or TXT.

{
  "success": false,
  "error": {
    "code": "INVALID_FILE_FORMAT",
    "message": "File must be CSV, JSON, or TXT format"
  }
}

FILE_TOO_LARGE (413)

Uploaded file exceeds 10MB limit.

{
  "success": false,
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File size exceeds 10MB limit"
  }
}

RATE_LIMIT_EXCEEDED (429)

Too many requests within your rate window.

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again later."
  }
}

RESULTS_EXPIRED (410)

Bulk job results are deleted after 7 days.

{
  "success": false,
  "error": {
    "code": "RESULTS_EXPIRED",
    "message": "Job results have expired and been deleted"
  }
}

INTERNAL_ERROR (500)

Unexpected server-side error.

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again."
  }
}

4. Error Handling Best Practices

Always check success before reading data

if (!response.success) {
  throw new Error(response.error.message);
}

Use error.code for programmatic handling

Avoid checking raw text messages.

Implement retry logic for:

429 (Rate limit exceeded)
500 (Server error)
503 (Service unavailable)

Log metadata.request_id

This helps support diagnose issues quickly.

For bulk jobs:

Pause processing when credits run out
Handle expired results using /download before 7 days

5. Quick Reference Table

Error Code	HTTP	Description	Common Cause
VALIDATION_FAILED	400	Invalid email format	Bad payload
UNAUTHORIZED	401	API key missing/invalid	Wrong header
INSUFFICIENT_CREDITS	402	No credits left	High usage
FORBIDDEN	403	Access denied	Wrong user
JOB_NOT_FOUND	404	Job missing	Wrong ID
RESULTS_EXPIRED	410	Expired dataset	Older than 7 days
FILE_TOO_LARGE	413	>10MB file	Large CSV
RATE_LIMIT_EXCEEDED	429	Too many requests	Burst traffic
INTERNAL_ERROR	500	Server issue	Unexpected error

‹

Credits & Billing ›

Search Docs…