API reference

Errors

Handle IronDome API errors for invalid requests, authentication, quotas and service failures. See response formats and when to retry.

On this page

Handle API errors separately from email classifications. A disposable address is a successful check; a timeout or unavailable service is not evidence that an address is acceptable.

Error format

JSON

{
  "error": {
    "code": "invalid_email",
    "message": "Provide a syntactically valid email address."
  }
}

Branch on HTTP status and error.code. Messages are explanatory and may change. Keep the X-Request-ID response header for troubleshooting; redact credentials and email bodies.

Status codes

Status	Codes	Recovery
`400`	`empty_body`, `invalid_content_length`, `invalid_body_length`, `invalid_json`	Correct the body schema or framing.
`400`	`empty_batch`	Provide at least one email.
`401`	`authorization_required`, `invalid_authorization`, `invalid_api_key`, `expired_api_key`, `inactive_api_key`, `revoked_api_key`	Check the full credential and its account status; replace it if necessary.
`403`	`insufficient_scope`	Use a credential permitted to perform the operation.
`403`	`free_usage_only`	Read paid usage in the dashboard instead of `/v1/usage`.
`404`	`not_found`	Check the route under `https://api.irondome.dev`.
`405`	`method_not_allowed`	Use the method in `Allow`.
`411`	`content_length_required`	Send a known-length JSON body.
`413`	`body_too_large`, `batch_too_large`	Reduce the body or split into batches of at most 100.
`422`	`invalid_email`	Ask the user to correct the address.
`429`	`monthly_quota_exceeded`	Wait for the UTC monthly reset or explicitly arrange paid access.
`500`	`internal_error`	Keep the request ID and investigate repeated failures.
`503`	`service_unavailable`	Preserve the unavailable state; respect `Retry-After` before another attempt.

Single-check bodies are limited to 1,024 UTF-8 bytes; bulk bodies to 65,536 bytes. See requests and bulk errors.

Bulk item errors

An accepted batch returns HTTP 200 even when individual emails are invalid. Inspect each item's error and use its zero-based index to match it to the submitted list.

Timeouts and retries

Authentication failures include WWW-Authenticate: Bearer. Service-unavailable responses include Retry-After: 5, in seconds. Free-quota exhaustion persists until monthly reset or an explicit authorization change; short retry loops do not help.

A lost response, canceled request, or timeout after submission is ambiguous: the check may have completed and consumed usage. The check endpoints provide no idempotency-key contract. Another attempt can count again.

Do not automatically retry malformed requests, invalid addresses, authentication failures, or exhausted quota. For transient failures, use bounded retries with backoff and jitter only if your application accepts possible repeated usage. Preserve a total deadline for signup.

Consult service status for persistent failures. Choose an explicit unavailable-check policy instead of returning an invented non-disposable result.

Supabase hook errors

The Supabase integration uses a hook envelope. Transport HTTP 200 with an error.http_code can deny signup. Do not apply REST success handling to hook responses.