Skip to content
RocketVerifierDOCS

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 body
{
  "error": {
    "code": "insufficient_credits",
    "message": "Need 2500 credits, have 1200",
    "details": { "required": 2500, "available": 1200 }
  }
}
FieldTypeMeaning
error.codestringMachine-readable code. Branch on this.
error.messagestringWhat went wrong, in plain words. Safe to log; show it to developers, not end users.
error.detailsobject or nullExtra 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#

Statuserror.codeCauseFix
401unauthorizedMissing Authorization header, missing Bearer prefix, or an unknown or revoked keySend Authorization: Bearer <key> with an active key
401api_key_expiredThe key passed its expiry dateExtend the expiry or create a new key
401invalid_tokenOAuth access token expired, revoked, or its app suspendedRefresh the token, or reconnect the user
403insufficient_scopeThe key or token lacks the scope this endpoint needsAdd the scope to the key or request it in your app
403ip_not_allowedThe caller's IP is outside the key's or organization's allowlistAdd the IP or range to the allowlist
403sandbox_key_restrictedAn rv_test_ key was used on a real address, or for a file uploadUse a live key, or sandbox addresses
403account_suspendedThe account is suspendedContact support@rocketverifier.com
403forbiddenThe request is not allowed for this accountCheck the account and resource

Authentication explains keys, scopes, expiry and allowlists.

Credit errors#

Statuserror.codeCauseFix
403insufficient_creditsThe 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
402insufficient_creditsThe 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
402api_key_spend_cap_reachedThe 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#

Statuserror.codeCauseFix
422validation_errorThe 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
400bad_requestThe request is malformedCheck the method, path and body
400no_emailsA bulk request or file has no addressesSend at least one address
400too_many_emailsMore than 100,000 unique addresses in a bulk request, or more than 5,000 in a monitorSplit the list into several jobs
400invalid_emailThe address is not a valid emailFix the address
400invalid_domainThe domain parameter is not a domain nameSend a bare domain such as northwind.io
400invalid_ipThe IP parameter is not a public IPv4 addressSend an address such as 192.0.2.10
400invalid_namefirst_name for the finder has no lettersSend a real first name
400invalid_urlA webhook URL is not HTTPSUse an https:// URL
400invalid_eventsA webhook subscribes to an unknown eventUse names from GET /v1/webhooks/events
400no_changesAn update request changes nothingSend at least one field
400domain_required, emails_required, invalid_emails, invalid_frequencyA monitor is missing its domain or emails, has addresses that fail syntax checks, or an unknown frequencyFix the monitor fields
400job_not_completeA download was requested before the job finishedWait for job.completed, then download
400job_not_cancellableThe job is no longer pending or processingNothing to do: it already finished
404not_foundThe job, webhook, monitor or route does not exist for this accountCheck the ID and the account behind the key

Upload errors#

These come from POST /v1/verify/bulk/upload and its preview and confirm steps.

Statuserror.codeCauseFix
400missing_fileNeither or both of file and source_url were sentSend exactly one
400invalid_jsonA JSON body could not be parsedSend a JSON object
400invalid_column_mappingcolumn_mapping or email_column is not validUse {"email": "Work Email"} or a 0-based index
400unsupported_file_typeThe file is not .csv, .tsv, .txt or .xlsxConvert the file
400empty_fileThe uploaded file is emptyUpload the file again
400invalid_callback_url, invalid_source_urlThe URL is not a public HTTPS URLUse a public https:// URL
411length_requiredThe upload has no Content-Length headerLet your HTTP client set it
413file_too_largeThe file is over 50 MBSplit the file, or compress columns you do not need
415unsupported_media_typeThe body is neither multipart/form-data nor JSONSend a file as multipart, or source_url as JSON
409preview_unavailableThe job was not created with preview=trueUpload with preview=true to get a free preview
409job_not_awaiting_confirmationThe job was already confirmed, cancelled or finishedRead 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#

Statuserror.codeCauseFix
429rate_limitedMore requests in the last 60 seconds than the limit allowsWait Retry-After seconds, then retry
429daily_limit_reachedThe free test lookup (POST /v1/tools/verify-free) allows 2 checks per IP per dayUse 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#

Statuserror.codeCauseFix
500internal_error, verification_failed, finder_failed, create_failedThe request could not be completedRetry with backoff and the same Idempotency-Key
502storage_unavailableAn uploaded file could not be storedRetry the upload
503service_unavailable, queue_unavailableA dependency is briefly unavailableRetry with backoff
503maintenanceBulk intake is paused for maintenance. Carries Retry-After: 600.Retry after the given seconds
503idempotency_unavailableAn Idempotency-Key was sent but the idempotency store is unreachable, so the request was refused rather than risk a double chargeRetry 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": "..."}.

StatuscodeCauseFix
401missing_key, invalid_keyThe embed has no key, or the key is unknown or inactiveCopy the embed code again from the dashboard
403origin_required, domain_not_allowedThe page's domain is not on the key's allowed domainsAdd the domain to the shield's settings
402insufficient_creditsThe account has no creditsAdd credits

Which errors to retry#

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

RetryDo not retry without a change
429 after Retry-After seconds400, 404, 409, 411, 413, 415, 422: fix the request
500, 502, 503 with exponential backoff401: fix or refresh the credential
Network errors and timeouts402, 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;
}

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:

SituationNode.jsPython
Invalid, missing or expired keyAuthenticationErrorAuthenticationError
Expired or revoked OAuth tokenInvalidTokenErrorInvalidTokenError
Out of creditsInsufficientCreditsError (402)InsufficientCreditsError (402 and 403)
Still rate limited after retriesRateLimitErrorRateLimitError
Invalid requestValidationError (400)ValidationError (400 and 422)
Scope, allowlist or sandbox refusalRocketVerifierError with codePermissionDeniedError with code
Anything elseRocketVerifierErrorRocketVerifierError

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