Errors, Rate Limits & Credits

Requests are metered two ways - how fast you call, and how many search credits you spend. Access also depends on domain authorization.

Request rate

Requests are rate-limited per token, about 1 request per second. Sending faster returns 429 with the X-RateLimit-Reason: rate_limit header.

Credits

• Every request costs 1 credit, including a request that returns 0 records and each Breach Catalog call.
• requestsLeft in every response shows your remaining balance.
• When credits run out, requests return 429 with the X-RateLimit-Reason: insufficient_credits header.

Domain authorization

You can only search domains authorized for your token. A queried domain is added automatically; a brand-new domain may take about 20 seconds to index on the first request. A very large unauthorized domain (over ~1,000,000 records in the past year) is blocked with 403 - contact support to enable it.

Error responses

Errors return { "errorCode": <code>, "errors": ["message", ...] }.

Status	When
400	Missing, unknown, duplicated, or malformed parameter; or a time filter older than one year without raw=true.
401	Missing or invalid token, or your account lacks the Data Breaches role.
402	Account email is not verified.
403	No authorized domains, an unauthorized domain, or a domain blocked by the safeguard.
404	Endpoint or resource not found, or no user for the token.
429	Rate limit exceeded, or insufficient credits (see X-RateLimit-Reason).
500	Internal error.
503	Service temporarily unavailable.