Response semantics

Finder and Probe return the same top-level result shape, so you can handle results consistently across both workflows.

Core fields

• state: The final verification result. This is deliverable or undeliverable.
• outcome: A compact request outcome such as found, not_found, or error.
• address: The resolved or verified email address when one is available.

Additional context

• identity_providers: Provider details associated with the result.
• mx_hosts: Observed mail routing hosts.
• request_id: A request identifier when available.

Error outcomes

outcome=error means the system could not complete verification cleanly. It is not the same as a confirmed negative result.

Finder bills only when outcome=found; not_found and error outcomes are free. Probe bills on any found or not_found result; error outcomes are free.

In practice:

• synchronous single-item calls should usually be retried later
• batch and background job results may contain a mix of found, not_found, and error
• item-level error responses are best treated as operational exceptions, not as mailbox verdicts

For client probe batch and background jobs, operational error items are not meant to be interpreted as “this mailbox does not exist.”

Background job semantics

Background jobs add two layers around the usual Finder and Probe result meanings:

• a job-level status such as queued, processing, completed, or failed
• item-level result semantics inside the job payload

A completed job can still contain some item-level outcome=error results while the overall job status remains completed.

Temporary busy responses

Some synchronous public endpoints may return 429 when real-time verification capacity is already full.

That response means:

• the request was not admitted for immediate synchronous execution
• the service is temporarily busy, not permanently unavailable
• background jobs remain the preferred fallback for work that can wait

Auth And Credits

• 401 means the bearer token is missing or invalid.
• 402 means the bearer token is valid but the request does not have enough prepaid credit or usage balance left.

For most integrations, state, outcome, and address are the three fields to handle first.