# Errors

Source: https://docs.rocketverifier.com/errors

> Every error returns the same JSON shape, an error object with a stable code, a readable message and optional details. Branch on error.code, not the message. Retry 429, 5xx and network failures with the same Idempotency-Key; fix the request for every other 4xx.

When a request fails, the HTTP status says what kind of problem it is and `error.code` says exactly which one. Codes are stable, so your code can branch on them; messages are written for people and can change.

## Error shape

Every error response, from every endpoint, has this body:

Error body:

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "Need 2500 credits, have 1200",
    "details": { "required": 2500, "available": 1200 }
  }
}
```

| Field | Type | Meaning |
| --- | --- | --- |
| `error.code` | string | Machine-readable code. Branch on this. |
| `error.message` | string | What went wrong, in plain words. Safe to log; show it to developers, not end users. |
| `error.details` | object or null | Extra data for some codes, such as `required` and `available` credits or the `errors` list of a validation failure. |

Every response also carries an `X-Request-ID` header. Send your own `X-Request-ID` (up to 128 characters) to tie API calls to your logs, and include it when you contact support.

## Authentication and access errors

| Status | `error.code` | Cause | Fix |
| --- | --- | --- | --- |
| 401 | `unauthorized` | Missing `Authorization` header, missing `Bearer ` prefix, or an unknown or revoked key | Send `Authorization: Bearer <key>` with an active key |
| 401 | `api_key_expired` | The key passed its expiry date | Extend the expiry or create a new key |
| 401 | `invalid_token` | OAuth access token expired, revoked, or its app suspended | Refresh the token, or reconnect the user |
| 403 | `insufficient_scope` | The key or token lacks the scope this endpoint needs | Add the scope to the key or request it in your app |
| 403 | `ip_not_allowed` | The caller's IP is outside the key's or organization's allowlist | Add the IP or range to the allowlist |
| 403 | `sandbox_key_restricted` | An `rv_test_` key was used on a real address, or for a file upload | Use a live key, or sandbox addresses |
| 403 | `account_suspended` | The account is suspended | Contact support@rocketverifier.com |
| 403 | `forbidden` | The request is not allowed for this account | Check the account and resource |

[Authentication](https://docs.rocketverifier.com/authentication) explains keys, scopes, expiry and allowlists.

## Credit errors

| Status | `error.code` | Cause | Fix |
| --- | --- | --- | --- |
| 403 | `insufficient_credits` | The balance is zero, so the request was refused before any work. Applies to verification, jobs, monitors, finder and uploads. | Add credits or turn on auto-recharge |
| 402 | `insufficient_credits` | The balance ran out while charging, or a bulk job needs more credits than remain. `details` holds `required` and `available`. | Add credits, or split the job |
| 402 | `api_key_spend_cap_reached` | The key's or app connection's monthly credit limit is used up. `details` holds `monthly_limit`, `used_this_month` and `required`. | Raise the limit, or wait for the next month (UTC) |

Read-only endpoints such as `GET /v1/credits`, `GET /v1/me` and the webhook endpoints work at a zero balance.

## Request errors

| Status | `error.code` | Cause | Fix |
| --- | --- | --- | --- |
| 422 | `validation_error` | The body is not valid JSON, a required field is missing, or a value is out of range (for example `timeout` outside 3 to 60). `details.errors` lists each problem. | Fix the fields listed in `details.errors` |
| 400 | `bad_request` | The request is malformed | Check the method, path and body |
| 400 | `no_emails` | A bulk request or file has no addresses | Send at least one address |
| 400 | `too_many_emails` | More than 100,000 unique addresses in a bulk request, or more than 5,000 in a monitor | Split the list into several jobs |
| 400 | `invalid_email` | The address is not a valid email | Fix the address |
| 400 | `invalid_domain` | The domain parameter is not a domain name | Send a bare domain such as `northwind.io` |
| 400 | `invalid_ip` | The IP parameter is not a public IPv4 address | Send an address such as `192.0.2.10` |
| 400 | `invalid_name` | `first_name` for the finder has no letters | Send a real first name |
| 400 | `invalid_url` | A webhook URL is not HTTPS | Use an `https://` URL |
| 400 | `invalid_events` | A webhook subscribes to an unknown event | Use names from `GET /v1/webhooks/events` |
| 400 | `no_changes` | An update request changes nothing | Send at least one field |
| 400 | `domain_required`, `emails_required`, `invalid_emails`, `invalid_frequency` | A monitor is missing its domain or emails, has addresses that fail syntax checks, or an unknown frequency | Fix the monitor fields |
| 400 | `job_not_complete` | A download was requested before the job finished | Wait for `job.completed`, then download |
| 400 | `job_not_cancellable` | The job is no longer pending or processing | Nothing to do: it already finished |
| 404 | `not_found` | The job, webhook, monitor or route does not exist for this account | Check the ID and the account behind the key |

## Upload errors

These come from [`POST /v1/verify/bulk/upload`](https://docs.rocketverifier.com/api/bulk-upload) and its preview and confirm steps.

| Status | `error.code` | Cause | Fix |
| --- | --- | --- | --- |
| 400 | `missing_file` | Neither or both of `file` and `source_url` were sent | Send exactly one |
| 400 | `invalid_json` | A JSON body could not be parsed | Send a JSON object |
| 400 | `invalid_column_mapping` | `column_mapping` or `email_column` is not valid | Use `{"email": "Work Email"}` or a 0-based index |
| 400 | `unsupported_file_type` | The file is not `.csv`, `.tsv`, `.txt` or `.xlsx` | Convert the file |
| 400 | `empty_file` | The uploaded file is empty | Upload the file again |
| 400 | `invalid_callback_url`, `invalid_source_url` | The URL is not a public HTTPS URL | Use a public `https://` URL |
| 411 | `length_required` | The upload has no `Content-Length` header | Let your HTTP client set it |
| 413 | `file_too_large` | The file is over 50 MB | Split the file, or compress columns you do not need |
| 415 | `unsupported_media_type` | The body is neither `multipart/form-data` nor JSON | Send a file as multipart, or `source_url` as JSON |
| 409 | `preview_unavailable` | The job was not created with `preview=true` | Upload with `preview=true` to get a free preview |
| 409 | `job_not_awaiting_confirmation` | The job was already confirmed, cancelled or finished | Read the job status instead |

Problems found while reading the file fail the job and fire the `job.failed` webhook: no email column (`email_column_not_found`), no rows (`no_emails`), an unreadable spreadsheet (`invalid_file`) or more than 500,000 unique addresses (`too_many_emails`).

## Rate limit errors

| Status | `error.code` | Cause | Fix |
| --- | --- | --- | --- |
| 429 | `rate_limited` | More requests in the last 60 seconds than the limit allows | Wait `Retry-After` seconds, then retry |
| 429 | `daily_limit_reached` | The free test lookup (`POST /v1/tools/verify-free`) allows 2 checks per IP per day | Use `POST /v1/verify` with an API key |

A `rate_limited` response carries `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers, and `details.retry_after_seconds`. [Rate limits](https://docs.rocketverifier.com/rate-limits) lists the limits for each plan.

## Server errors

| Status | `error.code` | Cause | Fix |
| --- | --- | --- | --- |
| 500 | `internal_error`, `verification_failed`, `finder_failed`, `create_failed` | The request could not be completed | Retry with backoff and the same `Idempotency-Key` |
| 502 | `storage_unavailable` | An uploaded file could not be stored | Retry the upload |
| 503 | `service_unavailable`, `queue_unavailable` | A dependency is briefly unavailable | Retry with backoff |
| 503 | `maintenance` | Bulk intake is paused for maintenance. Carries `Retry-After: 600`. | Retry after the given seconds |
| 503 | `idempotency_unavailable` | An `Idempotency-Key` was sent but the idempotency store is unreachable, so the request was refused rather than risk a double charge | Retry shortly with the same key |

## RocketShield widget errors

The [RocketShield](https://docs.rocketverifier.com/integrations/widget) form widget calls its own endpoint with a public key and returns a flat body, `{"code": "...", "message": "..."}`.

| Status | `code` | Cause | Fix |
| --- | --- | --- | --- |
| 401 | `missing_key`, `invalid_key` | The embed has no key, or the key is unknown or inactive | Copy the embed code again from the dashboard |
| 403 | `origin_required`, `domain_not_allowed` | The page's domain is not on the key's allowed domains | Add the domain to the shield's settings |
| 402 | `insufficient_credits` | The account has no credits | Add credits |

## Which errors to retry

Retry only when the same request can succeed later. Everything else needs a change first.

| Retry | Do not retry without a change |
| --- | --- |
| `429` after `Retry-After` seconds | `400`, `404`, `409`, `411`, `413`, `415`, `422`: fix the request |
| `500`, `502`, `503` with exponential backoff | `401`: fix or refresh the credential |
| Network errors and timeouts | `402`, `403`: add credits, scopes or allowlist entries |

Send an `Idempotency-Key` on every `POST`, and reuse it on each retry of the same logical request. Within 24 hours the API returns the stored result instead of verifying and charging again. An `unknown` verification result is a `200`, not an error: retry it after its `retry_after` seconds, as described in [reading results](https://docs.rocketverifier.com/results#retry-unknown-results).

## Handle errors in code

This client retries what is safe to retry, honours `Retry-After`, reuses one idempotency key across attempts and surfaces everything else with its code.

Node.js:

```js
import { randomUUID } from "node:crypto";

const RETRYABLE = new Set([429, 500, 502, 503]);

export class RocketVerifierApiError extends Error {
  constructor(status, body, requestId) {
    super(body?.error?.message ?? `HTTP ${status}`);
    this.status = status;
    this.code = body?.error?.code ?? "unknown_error";
    this.details = body?.error?.details ?? null;
    this.requestId = requestId;
  }
}

export async function rvRequest(path, body, { maxAttempts = 4 } = {}) {
  const idempotencyKey = randomUUID(); // same key for every attempt
  for (let attempt = 1; ; attempt++) {
    let res;
    try {
      res = await fetch(`https://api.rocketverifier.com${path}`, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.ROCKETVERIFIER_API_KEY}`,
          "Content-Type": "application/json",
          "Idempotency-Key": idempotencyKey,
        },
        body: JSON.stringify(body),
        signal: AbortSignal.timeout(35_000),
      });
    } catch (networkError) {
      if (attempt >= maxAttempts) throw networkError;
      await sleep(backoff(attempt));
      continue;
    }

    if (res.ok) return res.json();

    const errorBody = await res.json().catch(() => null);
    if (RETRYABLE.has(res.status) && attempt < maxAttempts) {
      const retryAfter = Number(res.headers.get("Retry-After"));
      await sleep(retryAfter > 0 ? retryAfter * 1000 : backoff(attempt));
      continue;
    }
    throw new RocketVerifierApiError(res.status, errorBody, res.headers.get("X-Request-ID"));
  }
}

const backoff = (attempt) => Math.min(30_000, 500 * 2 ** attempt) + Math.random() * 250;
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

try {
  const result = await rvRequest("/v1/verify", { email: "maya@northwind.io" });
  console.log(result.status);
} catch (err) {
  if (err.code === "insufficient_credits") notifyBilling(err.details);
  else if (err.code === "api_key_spend_cap_reached") alertOps(err.details);
  else throw err;
}
```

Python:

```python
import os
import random
import time
import uuid

import requests

RETRYABLE = {429, 500, 502, 503}

class RocketVerifierApiError(Exception):
    def __init__(self, status: int, body: dict | None, request_id: str | None):
        error = (body or {}).get("error") or {}
        super().__init__(error.get("message") or f"HTTP {status}")
        self.status = status
        self.code = error.get("code", "unknown_error")
        self.details = error.get("details")
        self.request_id = request_id

def backoff(attempt: int) -> float:
    return min(30.0, 0.5 * 2**attempt) + random.random() / 4

def rv_request(path: str, body: dict, max_attempts: int = 4) -> dict:
    idempotency_key = str(uuid.uuid4())  # same key for every attempt
    for attempt in range(1, max_attempts + 1):
        try:
            res = requests.post(
                f"https://api.rocketverifier.com{path}",
                headers={
                    "Authorization": f"Bearer {os.environ['ROCKETVERIFIER_API_KEY']}",
                    "Idempotency-Key": idempotency_key,
                },
                json=body,
                timeout=35,
            )
        except requests.RequestException:
            if attempt == max_attempts:
                raise
            time.sleep(backoff(attempt))
            continue

        if res.ok:
            return res.json()

        if res.status_code in RETRYABLE and attempt < max_attempts:
            retry_after = int(res.headers.get("Retry-After") or 0)
            time.sleep(retry_after or backoff(attempt))
            continue

        try:
            error_body = res.json()
        except ValueError:
            error_body = None
        raise RocketVerifierApiError(res.status_code, error_body, res.headers.get("X-Request-ID"))

try:
    result = rv_request("/v1/verify", {"email": "maya@northwind.io"})
    print(result["status"])
except RocketVerifierApiError as err:
    if err.code == "insufficient_credits":
        notify_billing(err.details)
    elif err.code == "api_key_spend_cap_reached":
        alert_ops(err.details)
    else:
        raise
```

### With the SDKs

The Node.js and Python SDKs already retry `429` responses (honouring `Retry-After`) and network errors, up to 3 times by default with the same idempotency key. They raise typed errors that carry `code`, the HTTP status and `details`:

| Situation | Node.js | Python |
| --- | --- | --- |
| Invalid, missing or expired key | `AuthenticationError` | `AuthenticationError` |
| Expired or revoked OAuth token | `InvalidTokenError` | `InvalidTokenError` |
| Out of credits | `InsufficientCreditsError` (402) | `InsufficientCreditsError` (402 and 403) |
| Still rate limited after retries | `RateLimitError` | `RateLimitError` |
| Invalid request | `ValidationError` (400) | `ValidationError` (400 and 422) |
| Scope, allowlist or sandbox refusal | `RocketVerifierError` with `code` | `PermissionDeniedError` with `code` |
| Anything else | `RocketVerifierError` | `RocketVerifierError` |

Check `err.code` in either SDK for the exact API code, such as `ip_not_allowed` or `api_key_spend_cap_reached`. The SDK pages, [Node.js](https://docs.rocketverifier.com/sdks/nodejs) and [Python](https://docs.rocketverifier.com/sdks/python), list every class.

## Next steps

- [Rate limits](https://docs.rocketverifier.com/rate-limits)
Limits per plan, headers and backoff for 429.
- [Authentication](https://docs.rocketverifier.com/authentication)
Keys, scopes, expiry, IP allowlists and spend caps.

## Frequently asked questions

### Is it safe to retry a POST that timed out?

Yes, when you send an Idempotency-Key header. A retry with the same key within 24 hours returns the original result and never charges twice. The Node.js and Python SDKs add a key to every POST automatically.

### Why do I get 403 insufficient_credits and sometimes 402 insufficient_credits?

403 means the balance was already zero, so the request was refused before any work. 402 means the balance ran out while charging this request, for example a bulk job larger than the remaining credits. Both are fixed by adding credits.

### Are failed requests charged?

No. Credits are only spent on a successful verification that returns a result. Errors, unknown results and requests refused for credits, scope or rate limits cost nothing.

### What should I send to support about an error?

The X-Request-ID response header, the error code and the time of the request. Every response carries an X-Request-ID, and you can set your own on the request to match your logs.
