Docs/Error Codes

Error Codes

Reference for HTTP status codes, API error codes, and verification reason codes returned by RocketVerifier.

Error Response Format

All API errors return a JSON object with an error key containing code, message, and optional details.

HTTP Error Codes

400invalid_email

Bad Request

The request body or parameters are invalid.

{
  "error": {
    "code": "invalid_email",
    "message": "The email address format is invalid",
    "details": null
  }
}

401unauthorized

Unauthorized

Missing, invalid, or expired API key.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key",
    "details": null
  }
}

402insufficient_credits

Payment Required

Your account (or organization pool) does not have enough credits for this operation.

{
  "error": {
    "code": "insufficient_credits",
    "message": "You don't have enough credits for this operation",
    "details": {
      "required": 100,
      "available": 50
    }
  }
}

403insufficient_scope

Forbidden — Insufficient Scope

The API key lacks the required permission scope for this endpoint.

{
  "error": {
    "code": "insufficient_scope",
    "message": "Scope 'verify:bulk' required",
    "details": null
  }
}

403ip_not_allowed

Forbidden — IP Not Allowed

The request originated from an IP address not on the API key's allowlist.

{
  "error": {
    "code": "ip_not_allowed",
    "message": "Request from IP 203.0.113.42 is not allowed for this API key",
    "details": null
  }
}

403subscription_required

Forbidden — Subscription Required

An active subscription is required to use the API.

{
  "error": {
    "code": "subscription_required",
    "message": "Active subscription required",
    "details": null
  }
}

404not_found

Not Found

The requested resource (job, webhook, etc.) does not exist.

{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found",
    "details": null
  }
}

429rate_limited

Too Many Requests

Rate limit exceeded. Check X-RateLimit-* headers and Retry-After before retrying.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please retry after 60 seconds.",
    "details": {
      "limit": 100,
      "remaining": 0,
      "reset_at": 1640995200
    }
  }
}

500verification_failed

Internal Server Error

An unexpected error occurred during processing.

{
  "error": {
    "code": "verification_failed",
    "message": "Verification could not be completed",
    "details": null
  }
}

API Key Scopes

Each API key is assigned permission scopes. Requests to endpoints outside the key's scopes return 403 insufficient_scope.

Scope	Grants Access To
verify:single	POST /v1/verify — single email verification
verify:bulk	POST /v1/verify/batch — batch verification jobs
jobs:read	GET batch job status and download results
*	Full access to all scoped endpoints

Verification Reason Codes

Successful verification responses include a reason field explaining why the address received its status classification.

Reason Code	Description
accepted_email	Email passed all checks and is deliverable.
rejected_email	SMTP server rejected the address.
invalid_syntax	Email address format is invalid.
invalid_domain	The domain does not exist.
no_mx_record	No MX records found for the domain.
disposable_email	Address uses a known disposable email provider.
role_based	Address is role-based (e.g. info@, admin@).
catch_all	Domain accepts all addresses (catch-all).
account_disabled	Mailbox exists but is disabled.
mailbox_full	Mailbox exists but is full.
known_complainer	Address flagged as a known complainer or abuse reporter.
spam_trap	Address matches spam-trap heuristics (see below).
unknown	Status could not be determined.

Spam Trap Detection

When spam_trap is "yes" in the response, the address matched one of these heuristic signals. The reason field will be spam_trap.

Internal Reason	Description
typo_trap_domain	Domain is a known typo-trap (e.g. gmial.com, hotmial.com).
trap_local_pattern	Local part matches a trap pattern (e.g. spamtrap@, honeypot@).
pristine_catch_all	Catch-all domain with no web presence — pristine trap heuristic.

Example response with spam trap flag

{
  "email": "spamtrap@gmial.com",
  "status": "undeliverable",
  "reason": "spam_trap",
  "spam_trap": "yes",
  "domain": { "name": "gmial.com", "acceptAll": "no", "disposable": "no", "free": "no" },
  "score": 15
}