API Status & Error Codes | BounceShift Developers

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

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.
timeout_exceeded / smtp_inconclusive — the probe couldn't complete, so the status is unknown.
mx_only_unverified — MX exists but the mailbox couldn't be probed.

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.

Status & error codes

Validation statuses

Sub-statuses

HTTP response codes

SDK exceptions

See also

Why we abstain instead of guessing

Ready to Try BounceShift?