# Errors

Every failure returns an HTTP error status and the same small body, so one handler covers them all:

```json
{
  "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](/security) 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](/docs/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](/docs/api). |
| 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](/docs/authentication). |
| 402 | `insufficient_credits` | Your balance doesn't cover the call's price. Nothing ran. | Top up on [pricing](/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](/docs/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](/docs/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. |
