Errors

Every error has the same shape and a stable machine-readable code. Match on code, never on the message text. Messages get reworded, codes do not.

The shape

Error response

{
  "error": {
    "code": "quota_exceeded",
    "message": "You have used all 15 free lookups. Subscribe to continue."
  }
}

Codes

Status	Code	Meaning
401	missing_api_key	No Authorization header was sent.
401	invalid_api_key	The key is wrong or has been revoked.
402	quota_exceeded	Free trial used up, or the monthly plan limit reached.
404	lookup_not_found	No lookup with that id on your account.
422	missing_query	Send one of query, email, or phone.
429	rate_limit_exceeded	Too many requests this minute. Back off and retry.
500	internal_error	Our fault. Safe to retry.

402 is not 429

They look similar and need opposite responses. 429 means you are going too fast. Wait and retry, the window resets each minute. 402 means you are out of lookups, so retrying will never succeed. Someone has to upgrade or raise the limit.

A failed platform check is not an error

If a platform blocks us or times out, the lookup still returns 200, and that platform is simply absent from results. You will not get an error for it, because a partial answer is still a useful answer, and reporting an unreachable site as “not registered” would be worse than saying nothing.