Platform
Errors
In short
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.
On this page
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": {
"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 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 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 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 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.
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.
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;
}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:
raiseWith 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 and Python, list every class.
Next steps#
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.
Updated 11 November 2026Suggest an edit