Error Handling

Check HTTP status first, then read the validation fields. Invalid syntax, missing mail DNS, and disposable detection return 200; this means the check completed, not that the address passed.

Requests the API cannot process return a non-success status, usually with a JSON error message. Do not require that body shape to recognize a failure: session errors and upstream failures may return a different JSON structure or HTML.

Validation results are not errors

Input	Response	Status
Malformed email (not-an-email)	{ "format": false, ... }	200
Missing/empty email or domain	{ "format": false, ... }	200
Domain with no mail servers	{ "dns": false, ... }	200
Temporarily inconclusive DNS result	Result + dns_indeterminate signal	200
Disposable address	{ "disposable": true, ... }	200
Feature not on your plan	Result + requires_upgrade array	200

Error response

A typical API error:

{
  "error": "Invalid API key"
}

Rate-limit and quota errors include extra context to help you back off or upgrade:

{
  "error": "Rate limit exceeded",
  "retry_after": 60,
  "upgrade_url": "https://disify.com/pricing",
  "upgrade_message": "Need higher limits? Create a free account for 60 req/min, or upgrade to Pro for 500 req/min."
}

Status codes

Code	Meaning	Example messages
200	Success — includes valid, invalid-format, no-DNS, and disposable results.	—
401	Invalid API key.	Invalid API key
403	Access denied or account suspended.	Access denied, Account suspended
413	Bulk input exceeds 2,000,000 bytes.	Bulk input is too large.
422	Unprocessable input.	Input too long, Maximum 10,000 unique emails allowed.
429	Rate limit or quota exceeded, or too many invalid key attempts.	Rate limit exceeded, New free account daily quota exceeded, Free daily validation quota exceeded, Free monthly quota exceeded, Too many invalid API key attempts
503	A required service or bounded processing buffer is temporarily unavailable.	Service temporarily unavailable

Handling rate limits

• Per-minute limits: wait for Retry-After / retry_after before retrying.
• Daily or monthly quotas: use reset_at; rapid retries will not help.
• Bulk admission limits: wait for the current job or the cooldown described in the message.
• Invalid-key attempt limits: fix authentication before retrying.

Retry and upgrade fields are not present on every 429. See Rate Limits and Bulk Validation.

Handling temporary unavailability

A 503 is retryable. The generic Service temporarily unavailable response includes both a retry_after value and a Retry-After header; wait at least that many seconds and retry with jitter. Other 503 responses may provide retry guidance only in the message. Never treat a 503 as an invalid API key or prompt the customer to replace their key.

A core result containing the dns_indeterminate signal is also retryable, but remains a 200 because non-DNS checks completed normally. Do not interpret its dns: false value as confirmed absence of mail servers. Requested fields listed in temporarily_unavailable_features should likewise be retried later.