Status & error codes

Validation statuses

Every result carries a status and a 0–100 confidence score. An address is safe to send when its status is valid or catch_all. We report an honest unknown rather than a false valid when a probe is inconclusive — see how we measure accuracy.

Status	Meaning	Safe to send?
valid	The mailbox exists and is safe to send to.	Yes
invalid	Confirmed undeliverable — bad syntax, no MX records, or no mailbox. Remove it.	No
risky	Deliverable but elevated risk — for example a catch-all with no positive signals.	No
catch_all	An accept-all domain: the individual mailbox cannot be confirmed. Confidence reflects deliverability likelihood — send with caution.	Yes
unknown	The probe was inconclusive (greylisting, throttling, a blocked port). Retry later — this is not the same as invalid.	No
disposable	A throwaway address from a temporary-mail service.	No
spamtrap	A spam trap used to catch poor list hygiene. Never send.	No
abuse	A known complainer / abuse address. Never send.	No
do_not_mail	A forwarding service or an address you should not mail.	No

Recommendation & quality score

Because status is a strict machine value (and risky covers both "unverifiable junk" and "seen delivering reliably, just not SMTP-verified"), every response also includes a plain-English recommendation, a 0–100 quality_score, and an explanation sentence. Use recommendation to decide what to do:

Recommendation	What it means
deliverable	This mailbox is real and can receive mail — safe to send.
send_with_caution	Positive signals but not fully verified — reasonable to send, watch for bounces.
risky	Little or negative evidence — sending is likely to bounce or hurt your reputation.
undeliverable	Confirmed not safe to send — do not mail.
unknown	We could not determine deliverability — you are not charged for this.

An address seen delivering reliably in our network with no bounces returns status: risky but recommendation: send_with_caution with a high quality_score — it is a real, active mailbox, not a warning to avoid it.

Sub-statuses

Alongside the headline status, each result includes a granular sub_status explaining why. Common values include:

• mailbox_exists — the SMTP probe confirmed the mailbox.
• mailbox_not_found — the server rejected the recipient (no such user).
• no_mx_records — the domain has no mail server, so nothing is deliverable.
• invalid_format — the address failed syntax checks.
• greylisted — the server deferred us; retried on a schedule.
• google_not_probed / microsoft_not_probed / yahoo_not_probed / apple_not_probed — consumer mailboxes at these providers can't be verified over SMTP (they reject probes for real addresses too), so we don't probe them; the verdict comes from reputation data instead, and you're never charged for it.
• timeout_exceeded / smtp_inconclusive / smtp_blocked — the probe couldn't complete, so the status is unknown.
• mailbox_full — the mailbox exists but is over quota; mail to it would bounce right now.
• mx_only_unverified — MX exists but the mailbox couldn't be probed.
• mx_lookup_failed — the domain's DNS didn't respond in time (slow nameserver); reported unknown, not invalid — the address may be perfectly valid.

Typo suggestions: did_you_mean

Every response carries a did_you_mean field. It is a corrected address when the domain is within one or two character edits of a major provider, and null otherwise:

{
  "email": "[email protected]",
  "status": "disposable",
  "did_you_mean": "[email protected]"
}

Two things worth knowing about it.

First, it is advisory and never changes the verdict. We validate the address you sent, not the one we suggest — the mailbox at the misspelled domain may genuinely exist. Do not substitute the suggestion silently; show it to the person who typed it and let them confirm. At a signup form, that is a "did you mean [email protected]?" prompt before submit.

Second, it is populated whatever the status, including on addresses we return as valid or disposable. That matters because the misspellings that hurt most are the ones that resolve: gmil.com and hotmial.com are registered and accept mail, so they never bounce and never appear in a bounce report. The suggestion is the only signal you will get about them.

Batch results carry the same value in a did_you_mean column in the results CSV, and the batch view in the dashboard summarises how many addresses had one.

HTTP response codes

Code	Meaning
200	Success — the address was validated.
400	Bad request — invalid parameters, or no organization selected.
401	Unauthorized — invalid or missing API token.
402	Payment required — insufficient credits.
403	Forbidden — the token lacks the required permission, or the organization is invalid.
404	Not found — the resource does not exist.
422	Unprocessable entity — request validation failed.
429	Too many requests — rate limit exceeded (60 requests/minute).

SDK exceptions

The official SDKs map error responses to typed exceptions so you can catch each case:

HTTP	PHP / Laravel	Node
401	AuthenticationException	AuthenticationError
402	InsufficientCreditsException	InsufficientCreditsError
403	ForbiddenException	ForbiddenError
429	RateLimitException	RateLimitError
other	ApiException / BounceShiftException	ApiError / BounceShiftError

Rate-limit errors expose the retryAfter value; both SDKs also retry 429 and 5xx automatically with a clamped backoff.

See also

• Get started: API quickstart
• Full reference: interactive API docs · OpenAPI spec
• SDKs: all official SDKs