Errors

This is the catalogue of error codes VerifAi uses. Every error has a stable machine-readable code and a stable anchor on this page, so an error response can link you straight to its explanation.

Each entry’s anchor (the #fragment in its link) is permanent. Bookmark or link to them freely; we will not rename them.

invalid_request — 400

The request was malformed — a missing required field, a value of the wrong type, or an unparseable body. Fix the request shape and retry. Retrying the same request unchanged will fail identically.

invalid_api_key — 401

The API key was missing, malformed, revoked, or expired. Check that you are sending your key and that it is still active. This is an authentication failure, not a permission one.

revoked_api_key — 401

The API key was explicitly revoked and can no longer authenticate. Revocation takes effect immediately and is permanent for that key — the next request made with it is rejected. Create a fresh key on your API keys page and update your integration. Like invalid_api_key, this is an authentication failure, not a permission one.

insufficient_credits — 402

Your request was well-formed and authenticated, but your account has no credits left for a billable check. Add pay-as-you-go credits or upgrade your plan, then retry. Free checks (syntax, unknown results, re-validation under Always Clean) are never blocked by this. For jobs, this is only returned up front when your balance is already zero and the requested depth is billable; a job that runs out of credits mid-run still completes, returning the remaining billable rows as unknown at no charge.

forbidden — 403

Your key is valid but is not permitted to perform this action — for example, requesting a depth your plan does not include. This will not resolve on retry; it needs a plan or scope change.

not_found — 404

The addressed resource does not exist for your account. To keep tenants isolated, asking for a record that belongs to someone else returns not_found rather than revealing that it exists elsewhere.

job_not_found — 404

No job with that id exists for your account. Requesting a job that belongs to another account returns job_not_found rather than 403 — a 403 would confirm the id exists. Check the job_id from the submission response.

list_not_found — 404

No list with that id exists for your account. Requesting a list that belongs to another account returns list_not_found rather than 403 — a 403 would confirm the id exists. This applies to GET /v1/lists and the in-app list health view alike.

job_not_ready — 409

The job has not finished yet. Poll the job status until it reports completed, then download the result. Downloading a job result before it is ready returns this JSON error envelope, never an empty file. Read result_url from the job-status response once status is completed.

no_email_column — 422

No email column could be detected in the uploaded file. Supply a column mapping or include a column named 'email'. VerifAi auto-detects the email column by header name first, then by inspecting values — if neither succeeds, the file upload is rejected with this code.

file_empty — 400

The uploaded file is empty or contains no data rows. Send a CSV with a header row and at least one data row to POST /v1/files.

list_too_large — 413

This file exceeds your plan’s list-size limit. Split the list into smaller files, or upgrade your plan. Applies to POST /v1/files uploads.

payload_too_large — 413

The request body carries more addresses than POST /v1/evaluate accepts. Called anonymously, the free List Evaluator caps a request at 5,000 addresses; send fewer, authenticate with an API key to lift the cap, or use POST /v1/files for very large lists.

batch_too_large — 400

The emails array exceeds the maximum of 10000. Upload larger lists via POST /v1/files. Applies to POST /v1/validate/batch.

rate_limited — 429

You are sending requests faster than your plan allows. The limit is applied per API key, per minute. Slow down and retry after the interval given in the Retry-After response header. Bursts are smoothed; sustained overage is rejected until the window resets.

internal_error — 500

Something failed on our side. These are safe to retry with backoff. A billable check that ends in an internal error is not charged — see How billing works.