Errors

All errors are returned as JSON with an error message and the appropriate HTTP status.

{ "error": "Insufficient credits" }

Status codes

Status	Meaning
`400`	Invalid request. Bad role, malformed URL, URL too long, or missing required field.
`401`	Missing, invalid, or revoked API key.
`402`	Insufficient credits. Top up in the dashboard.
`404`	Resource not found, or belongs to a different team.
`409`	A matching search is already in progress. Poll the existing `searchId`.
`429`	Rate limit exceeded. Honor the `Retry-After` header.
`500`	Unexpected server error. Safe to retry after a short delay.

429 and 5xx: safe to retry with backoff.
400, 401, 402, 404: the request itself is wrong. Do not retry.
409: you have an in-flight search. Poll its status instead of retrying find-email.

Forgetting the Content-Type: application/json header: returns 400 Invalid JSON body.
Using a revoked key: returns 401 Invalid or revoked API key. Create a new key in the dashboard.
Submitting a role outside the allowlist: returns 400 with the list of valid roles. Use exact casing.