Errors

A successful response contains only the result. An error contains one error object with a type and a message. There is no other envelope, and the HTTP status code tells you what happened:

{
    "error": {
        "type": "AuthorizationError",
        "message": "Invalid or revoked API key."
    }
}

Branch on the status code and error.type, never on message. Messages are written for developers and may change; show your own text to end users.

Status codes for POST /v1/check

Status	type	When	Counted	What to do
200		The address was checked. The body is the result	Yes	See Check an email
400	ValidationError	The value is not an email address (Invalid email "nope": expected local@domain)	Yes	Ask the user for a valid email address
400	ValidationError	The body is not valid JSON (Request body must be valid JSON.)	No	Fix your request
401	AuthorizationError	API key missing, malformed, unknown or revoked	No	Check your key: see Authentication
404	NotFoundError	Unknown path	No	Check the URL (/v1/check)
413	ValidationError	Request body too large (Request body is too large.)	No	Send only { "email": "..." }
422	ValidationError	No JSON body, or email missing, not a string, empty or over 254 characters (email is required)	No	Fix your request
429	QuotaExceededError	Monthly quota used up. Retry-After = seconds until the 1st, 00:00 UTC	No	Don't retry this month. Upgrade or wait for the reset
429	RateLimitError	Too many requests per second. Retry-After: 1	No	Slow down: see Rate limits
500	InternalServerError	Unexpected error on our side	No	Fail open
503	InternalServerError	The check is temporarily unavailable, or the request took longer than 30 seconds	No	Fail open

In a signup flow, every row except 200 and 400 (not an email address) means: create the account as pending and recheck it later. See Never block a signup.

Error types

type	Meaning
ValidationError	The request or the email value is invalid
AuthorizationError	The API key is missing, invalid or revoked
NotFoundError	The resource does not exist
QuotaExceededError	The monthly quota is used up
RateLimitError	Too many requests in a short time
InternalServerError	Something failed on our side

Every response, including errors, has an x-request-id header. Include it when you report a problem.