1. Home
  2. API docs
  3. Errors

API errors and status codes

The API answers 200 with a verdict, or one of 400, 401, 402, 429 and 503 with a JSON body {"error": "..."}. Retry 429 (after Retry-After) and 503 (with backoff). Never retry 400, 401 or 402: they need a change on your side. A 402 has three different causes, listed below.

400 Bad request

Causes

  • The email parameter is missing, or the phone parameter is missing (phone endpoint).
  • The email is longer than 320 characters.

Fix: Send the address as email (query string on GET, JSON body on POST) and the number as phone.

Retry: No. The same request fails again.

401 Unauthorized

Causes

  • No key was sent. Use Authorization: Bearer sv_live_... (X-API-Key and ?api_key= also work, but headers keep keys out of logs).
  • The key is wrong or has been revoked.

Fix: Create or copy a key on the API keys page.

Retry: No.

402 Payment required

Causes

  • Your plan is Starter or Growth, which cover CSV verification in the dashboard but not the API or MCP.
  • The subscription behind the key is not active (cancelled, expired or unpaid).
  • You are on a yearly plan and this month's included calls are used. The reply carries a Retry-After header and retry_after_seconds with the seconds until 00:00 UTC on the 1st.

Fix: Upgrade to Pro, Business or Agency, renew the subscription, or wait for the monthly reset. Monthly plans never hit the quota case: calls past the included amount are billed per 1,000.

Retry: Not automatically. Only the quota case clears by itself, at the reset.

429 Too many requests

Cause

  • More than 120 calls in a sliding 60 seconds on one key.

Fix: Wait the number of seconds in the Retry-After header (the same number is retry_after_seconds in the body). For lists, upload a CSV in the dashboard instead.

Retry: Yes, after Retry-After. The official clients do this twice by default.

503 Service unavailable

Cause

  • The verification service did not answer or is restarting.

Fix: Retry with backoff. If your form blocks on this call, let the visitor through instead of rejecting them.

Retry: Yes, with exponential backoff. The official clients retry twice.

5xx Any other server error

Cause

  • An unexpected failure on our side.

Fix: Retry once. If it persists, email support@simpleverifier.com with the time and the key's last four characters, never the whole key.

Retry: Once or twice, then stop.

Example replies

Rate limited, 429:

HTTP/1.1 429
Retry-After: 23

{"error": "Rate limit reached", "retry_after_seconds": 23}

Yearly quota used, 402:

HTTP/1.1 402
Retry-After: 1036800

{"error": "This month's 10,000 API calls on Pro (yearly) are used. They reset on the 1st (UTC); ...", "retry_after_seconds": 1036800}

A 200 that is not a verdict

Some replies are 200 because the request worked, but no mailbox answer was reached. They are risky, never valid, and send_advice is retry:

  • Mailbox check unavailable: we could not reach the domain’s mail server.
  • Server would not confirm: the server deferred our check (greylisting or a temporary error).
  • DNS lookup failed; try again later: the domain’s DNS did not answer.
  • Provider is blocking our checks; not probed: that provider is refusing our server right now.
  • Daily mailbox-check limit reached; try again after 00:00 UTC: the reply also has budget_exhausted: true and retry_after (an ISO timestamp).

Treat these as “not checked”, not as bad addresses. Details in how a check works.

Webhooks

The API has no webhooks today, so there is nothing to verify or retry on that side. Single checks are synchronous; for lists, upload a CSV in the dashboard.

Common questions

Why does the SimpleVerifier API return 402?
Three causes: your plan is Starter or Growth, which have no API access; the subscription behind the key is not active; or you are on a yearly plan and this month's included calls are used (that reply has a Retry-After header with the seconds until the 1st, 00:00 UTC). Monthly plans never get the quota 402: calls past the included amount are billed per 1,000.
How long should I wait after a 429?
As long as the Retry-After header says. The same number of seconds is in the JSON body as retry_after_seconds. The limit is 120 calls a minute on one key, counted over a sliding 60 seconds.
Does a 200 always mean the mailbox was checked?
No. A 200 with status risky can mean the check could not be made: read reason and send_advice. send_advice retry means our check got no answer or the day's mailbox-check allowance was used, and the same address can be sent again after 00:00 UTC or a few minutes later.

API reference · Quickstart · SDKs · Status

Clean your next list before it bounces

100 free email checks when you sign in with Google, no card. Then monthly plans from $9, or one flat price with fair use, never cut off.

Check 100 emails freeSee pricing

100 free checks, no card Cancel anytime Secure payment by Stripe