Errors

Understand common errors and decide when a request should be retried.

SignupScore returns a normal HTTP status code and a short JSON message. If you contact support about an unexpected error, include the X-Request-ID response header.

Error body

Error response

{
  "error": "Human-readable message"
}

Use the status code in your application logic. The message is for people and may become more specific over time.

Status codes

Status	Example cause	What to do
`400`	`input` is missing or is not an email or domain.	Fix the request. Do not retry it unchanged.
`401`	The API key is missing, invalid, or revoked.	Check the key stored on your server.
`429`	Credits ran out or too many requests arrived together.	Read `X-Quota-Reset` or `Retry-After`.
`500`	SignupScore could not complete the check.	Retry briefly or use your chosen failure policy.

Retries

Retry network errors and 5xx responses with a short increasing delay, for example after 500 ms, 1 second, and 2 seconds. Stop after a few attempts so signup does not wait indefinitely.

For a short-burst 429, wait at least the number of seconds in Retry-After. If monthly credits are exhausted, X-Quota-Reset tells you when plan credits return.

Do not automatically retry 400 or 401. A retry will repeat the same mistake until the request or key changes.

Credits on errors

Invalid input, invalid keys, and rejected bursts use zero credits. If SignupScore cannot finish a check, the account does not keep the charge for that failed check.