Errors
Every failure returns an HTTP error status and the same small body, so one handler covers them all:
{
"error": {
"code": "insufficient_credits",
"message": "Your balance doesn't cover this call.",
"request_id": "0d3b7c1e-5f8a-4c2e-9b6d-2a1f4e7c9d10"
}
}
Switch on code: it never changes. The message is a plain sentence you can show to a person, and the
request_id (also in the X-Request-Id header) helps us find the call if you contact support. You
weren't charged for any error. When a status comes with a Retry-After header, wait that many seconds
before trying again.
Your request
| Status | Code | What it means | What to do |
|---|
| 400 | invalid_domain | The domain or host isn't a valid name. | Check the spelling; send a name like example.com, not a full address with spaces. |
| 400 | invalid_url | The URL can't be checked: not http or https, a port other than 80 or 443, or an IP address. | Send a public https:// address, or just the domain. |
| 400 | invalid_request | A parameter is missing or wrong, or an X-Request-Id was already used for a different call. | Read the message: it names the field. Send a new request ID for a new call. |
| 422 | invalid_request | A report sent through the security page holds control characters, so it can't be stored. | Remove them (new lines and tabs are fine) and send it again. |
| 400 | unsupported_tld | This tool can't check names under that TLD (the registry publishes no data). | See TLD coverage; a DNS lookup still works. |
| 400 | private_key_refused | The certificate decoder was sent something holding a private key. It was refused before reading it. | Send only the certificate or the CSR. Never paste a private key anywhere. |
| 400 | export_too_large | The report is too big to turn into a PDF. | Export it as JSON or CSV instead, or split the job. |
| 400 | token_invalid | A sign-in link, invite or passkey answer is unknown, used or expired. | Ask for a new link or invite. |
| 404 | not_found | Nothing at this path, or a job, stream, monitor or export that doesn't exist, has expired or isn't yours. | Check the ID and the address against the API reference. |
| 405 | method_not_allowed | The endpoint doesn't take that HTTP method. | Check the method in the reference. |
Your key and your account
| Status | Code | What it means | What to do |
|---|
| 401 | unauthorized | The API key is missing, unknown or revoked, or its creator left the account. | Send Authorization: Bearer <key> with a current key. See authentication. |
| 402 | insufficient_credits | Your balance doesn't cover the call's price. Nothing ran. | Top up on pricing, or wait for next month's credits. |
| 403 | account_suspended | The account is suspended. | Contact support. |
| 403 | sign_in_required | This needs an account; it was called without one. | Call it with an API key, or sign in on the website. |
| 403 | challenge_required | A free check on the website came without its proof-of-work. | Let the page finish loading with JavaScript on, then try again. |
| 403 | forbidden | Your role in this account doesn't allow it (owner-only actions). | Ask an owner of the account. |
| 403 | plan_limit | Your plan doesn't allow this: more seats, keys or members than it includes. | Upgrade the plan, or remove something first. |
| 403 | plan_kind | Your plan doesn't include this kind of monitor. | Pick a kind your plan includes, or upgrade. |
| 403 | interval_not_allowed | Your plan doesn't allow checks this often. | Choose a longer interval, or upgrade. |
| 403 | channel_not_allowed | Your plan doesn't include this alert channel type. | Use email alerts, or upgrade. |
| 403 | bulk_locked | Bulk checks unlock after your first credit purchase or plan. | Buy a pack or a plan, then try again. |
| 403 | verification_required | Large bulk jobs on these domains need proof that you control them. | Add the TXT record from POST /v1/verifications/record, then check it. |
| 403 | reauth_required | Deleting data needs a sign-in within the last 10 minutes. | Sign in again, then repeat the request. |
| 403 | password_required | The shared report has a password. | Ask the person who shared it for the password. |
Conflicts
| Status | Code | What it means | What to do |
|---|
| 409 | conflict | The request clashes with the current state, such as a second subscription. | Read the message, then reload what you have. |
| 409 | sole_owner | You are the only owner of an account that has other members. | Remove the members, or delete that account first. |
| 409 | duplicate_monitor | You already have this monitor. | Edit the existing monitor instead. |
| 409 | alerts_off | Alert sending is paused on this server, so test sends and webhook checks wait. | Try again later. |
| 409 | no_members | An account without members has no default alert channel. | Add an alert channel first. |
| 409 | channel_limit | The account already has the most alert channels it can have. | Remove one you no longer use. |
| 409 | channel_unverified | The webhook hasn't answered its verification yet. | Verify the channel, then attach it. See webhooks. |
Limits and busy services
| Status | Code | What it means | What to do |
|---|
| 429 | rate_limited | Too many requests for this key or option. | Wait for Retry-After. See rate limits. |
| 429 | free_limit_reached | A website visitor used today's free checks. | Make a free account, or wait until tomorrow (UTC). |
| 429 | too_many_jobs | Your account started too many browser or crawl jobs this hour. | Wait for Retry-After, or combine targets into one job. |
| 503 | busy | Too many live result streams are open right now. | Retry in a few seconds, or call the tool without streaming. |
| 503 | site_busy | The site you're checking is getting many checks right now. | Retry after 30 seconds. |
| 503 | browser_busy | All browser sessions are in use. | Retry after Retry-After. |
| 503 | crawl_busy | Too many link checks are running site-wide. | Retry after Retry-After. |
| 503 | bulk_busy | Too many bulk jobs are running site-wide. | Retry after Retry-After. |
| 503 | lookalike_busy | Too many lookalike checks are running site-wide. | Retry after Retry-After. |
| 503 | export_busy | The PDF store is full for now. | Retry after Retry-After, or export as JSON or CSV. |
| 503 | billing_unavailable | Payments aren't available right now. | Try again later; your credits and plan are unaffected. |
Sources and our side
| Status | Code | What it means | What to do |
|---|
| 502 | source_unavailable | Every source the check needs failed to answer (a DNS server, a registry or the site). | Retry later; a Retry-After header says when, if we know. |
| 503 | source_unavailable | The tool is paused for now, for example while its data refreshes. | Retry after Retry-After. |
| 500 | internal_error | Something went wrong on our side. | Retry in a minute; if it keeps happening, contact support with the request ID. |