> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keenable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Every page is listed in https://docs.keenable.ai/llms.txt. To pick a product for a job, read https://docs.keenable.ai/choose.md
> Setup steps for agents, covering the SDKs, the MCP server and the CLI: https://docs.keenable.ai/skill.md
> Keenable search and fetch work without an API key. To add them to code, use the official SDK for the project's language: https://docs.keenable.ai/sdks.md
> Without a key, call POST https://api.keenable.ai/v1/search/public or GET https://api.keenable.ai/v1/fetch/public with an X-Keenable-Title header that names your app.
> With a key, send it in the X-API-Key header and read it from the KEENABLE_API_KEY environment variable. Never ask a user to paste a key into chat. Every access method: https://docs.keenable.ai/auth.md
> To get an API key without the console, use device login: https://docs.keenable.ai/authentication.md#device-login
> MCP server: https://api.keenable.ai/mcp (no key, or X-API-Key; keyless Codex uses https://api.keenable.ai/mcp-public), or https://api.keenable.ai/mcp-oauth for OAuth sign-in. These docs are an MCP server at https://docs.keenable.ai/mcp and the OpenAPI spec is at https://docs.keenable.ai/api-reference/openapi.json
> Keenable searches and fetches public web pages. If a question needs no web information, skip the call.
> On 402 with an API key (code insufficient_credits), stop and ask a human to add credits; don't retry. On 429, wait the number of seconds in Retry-After, then retry. Before you ship, follow https://docs.keenable.ai/production.md
> Every error, with its cause and fix, is in https://docs.keenable.ai/errors.md and moving from another search API is covered in https://docs.keenable.ai/migrate.md
> Before you compare Keenable with another search API, read https://docs.keenable.ai/guides/evaluate-search-apis.md

# Keenable API errors

> Look up any Keenable API error by status or code: the cause, whether a retry helps, and the fix. Covers the error body, error types and SDK error classes.

Find any error the Keenable API returns, what caused it and the exact fix. Each section has a stable anchor, so SDK error messages and agents can link straight to it.

| Status | Error | Retry? |
| - | - | - |
| [`400`](#400-invalid-request) | Invalid request parameters | Fix, then retry |
| [`400`](#400-missing-app-identifier) | Missing app identifier | Fix, then retry |
| [`401`](#401-missing-key) | Missing key | Fix, then retry |
| [`401`](#401-malformed-key) | Malformed key | Fix, then retry |
| [`401`](#401-invalid-key) | Invalid key | Fix, then retry |
| [`401`](#401-invalid-token) | Invalid bearer token | Fix, then retry |
| [`402`](#402) | Out of funds | Do not retry |
| [`403`](#403) | Key rejected or revoked | Do not retry; check the key, then ask a human |
| [`403`](#403-time-machine-not-enabled) | Time Machine not enabled | Do not retry; remove `query_time` or ask a human |
| [`404`](#404) | Page not found | Fix the URL, then retry |
| [`405`](#405) | Wrong HTTP method | Fix the method, then retry |
| [`422`](#422) | Content could not be extracted | Fix the URL or skip; do not retry the same URL |
| [`429`](#429) | Rate limit exceeded | Wait, then retry |
| [`5xx`](#5xx) | Server error | Retry up to 3 times |

Over HTTP, an error body is JSON with an `error` and a `message` field. The SDKs raise an error whose message starts with the prefix shown under each entry, followed by the API's `message`. Each SDK page lists its error classes and whether the SDK retries each one: [TypeScript](https://docs.keenable.ai/sdks/typescript.md#errors), [Python](https://docs.keenable.ai/sdks/python.md#errors), [Go](https://docs.keenable.ai/sdks/go.md#errors) and [Rust](https://docs.keenable.ai/sdks/rust.md#errors).

## Troubleshooting

Start from what you see. Each row names the usual cause and the fix, and links the full entry.

| What you see | Usual cause | Fix |
| - | - | - |
| `400` `Missing app identifier` on a call without a key | The keyless `/public` paths need your app's name | Send an `X-Keenable-Title` header. See [400 Missing app identifier](#400-missing-app-identifier). |
| `401` from `/v1/search` or `/v1/fetch` | No key, or the key isn't in the `X-API-Key` header | Send the key in `X-API-Key`, or call the `/public` paths without one. See [401 Missing key](#401-missing-key). |
| `405` from fetch | Fetch was sent as a `POST` | Send `GET` with the page in the `url` query parameter. See [405](#405). |
| `429` with `public_rate_limit_hourly` | The keyless 1,000 requests per hour for your IP address are used up | Send an [API key](https://docs.keenable.ai/api-keys.md), or wait until `limit.resets_at`. See [429](#429). |
| `429` with `rate_limit_per_second` | Your organization sent more than its per-second limit | Wait the seconds in `Retry-After`, then retry with fewer calls in parallel. See [Production checklist](https://docs.keenable.ai/production.md#stay-under-your-rate-limit). |
| `402` with `insufficient_credits` | The monthly allowance and the prepaid balance are used up | Stop and ask a human to top up. Don't retry. See [402](#402). |
| `403` with `Feature not enabled` | [Time Machine](https://docs.keenable.ai/api-reference/time-machine.md) isn't turned on for your organization | Drop `query_time`, or ask Keenable to turn it on. See [403 Time Machine not enabled](#403-time-machine-not-enabled). |
| Fetch returns an older version of a page | Fetch returned Keenable's indexed copy | Pass `live=true`. See [Live fetch](https://docs.keenable.ai/guides/live-fetch.md). |
| `5xx` or timeouts | A failure on Keenable's side or at the target page | Check [status.keenable.ai](https://status.keenable.ai), then retry up to 3 times. See [5xx](#5xx). |
| Your agent answers from its own web search, not Keenable | The client's built-in web search is still on | See [Make Keenable the default web tool](https://docs.keenable.ai/default-web-tool.md). |

## Error body

Every error from the `/v1` endpoints, including their `/public` and `/v1/x402` twins, is one flat JSON object. Branch on `type` for the broad handling and on `code` for the specific case, never on the text of `error` or `message`. New codes may be added, so handle an unknown `code` by its `type`, or by its HTTP status if `type` is missing.

This `429` shows the fields an agent acts on:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "error": "Rate limit exceeded",
  "type": "rate_limit_error",
  "code": "rate_limit_per_second",
  "message": "Too many requests: your organization is limited to 10 requests per second. Wait until 2026-11-06T12:00:01.000Z (1s), then retry. For a higher limit, upgrade at https://app.keenable.ai/console/billing?tab=limits.",
  "fix": "Wait until 2026-11-06T12:00:01.000Z (1s), then retry. Keep under 10 requests per second, shared by all your organization's keys. For a higher limit, upgrade at https://app.keenable.ai/console/billing?tab=limits.",
  "docs_url": "https://docs.keenable.ai/errors#rate-limit-per-second",
  "request_id": "0196f0c2-7a51-7c3e-9b0e-2f4d8a1c5e77",
  "retryable": true,
  "retry_after_seconds": 1,
  "retryAfter": 1,
  "limit": { "scope": "organization", "window": "second", "max": 10, "resets_at": "2026-11-06T12:00:01.000Z" }
}
```

The response also carries a `Retry-After: 1` header. The fields sit at the top level, not nested under an `error` object as in Stripe's API, because released clients read `error` and `message` as top-level strings. Which fields appear depends on the error:

| Field | When it's set | What it means |
| - | - | - |
| `error` | Every error | Short error title, such as `Rate limit exceeded`. Kept unchanged for existing clients. |
| `type` | With `code` | The category of the error, one of the seven [error types](#error-types). |
| `code` | Every error on the endpoints above | Stable machine code in `snake_case`. Codes are only added, never renamed. The [error codes](#error-codes) list every value. |
| `message` | Most errors | What went wrong, in words. The wording may change, so don't parse it. |
| `fix` | With `code` | What to do next, including whether retrying helps. |
| `param` | On validation errors | The parameter or header that failed, such as `url` or `X-Keenable-Title`. |
| `docs_url` | With `code` | The section of this page for the code: `https://docs.keenable.ai/errors#` followed by the code with `_` replaced by `-`, such as `#rate-limit-per-second`. The name is `docs_url`, not Stripe's `doc_url`. |
| `request_id` | Whenever one is known | The same value as the `X-Request-Id` header. Include it when you [report a problem](#report-a-problem). |
| `retryable` | With `code` | `true` if the same request can succeed when sent again unchanged. `false` means change the request or follow `fix`. |
| `retry_after_seconds` | On errors where `retryable` is `true` | Seconds to wait before retrying. The `Retry-After` header carries the same value. |
| `retryAfter` | On `429`s from Keenable's own rate limits | Older name for `retry_after_seconds`, kept for existing clients. |
| `allowed` | On `unknown_parameter` | The parameters the endpoint accepts. |
| `did_you_mean` | On `unknown_parameter`, when a name is close to a supported one | Maps each such name to the parameter to rename it to, such as `{"count": "max_results"}`. |
| `field`, `value`, `reason` | On a rejected `exclude_domains`, where `error` is `invalid_filter` | The filter, the entry or limit it rejected, and why. See [Exclude domains](https://docs.keenable.ai/api-reference/search.md#rejected-entries). |
| `details` | On `invalid_request` | Each field that failed schema validation. |
| `limit` | On `429`s from Keenable's own rate limits | Which limit you hit: `scope` (`organization`, `user`, `ip`, `payer` or `agent`), `window` (`second`, `minute` or `hour`), `max` requests per window, and `resets_at`, when you can send the next request. |
| `billing_url` | On `insufficient_credits` | Where to top up your balance. |
| `auto_top_up_url` | On `insufficient_credits` | How to turn on [auto top-up](https://docs.keenable.ai/auto-top-up.md). |
| `pay_per_request` | On `insufficient_credits`, where pay-per-request is enabled | The [x402](https://docs.keenable.ai/pay-per-request.md) alternative, which needs no key or balance. |
| `api_keys_url` | On authentication errors and `payment_required` | Where to create or copy an API key. |
| `keyless` | On `401` and `credentials_forbidden` errors from `/v1/search` and `/v1/fetch` | The keyless `/public` alternative. |

No error body echoes your API key or your request body.

## Error types

`type` is one of a closed set of seven values. The type belongs to the code, not to the HTTP status: `target_blocked` and `credentials_forbidden` are both `403`, but the first is a `target_error` and the second a `permission_error`.

| Type | Statuses | What it means | What to do |
| - | - | - | - |
| [`invalid_request_error`](#invalid-request-error) | `400`, `404`, `405`, `406`, `409`, `413`, `415`, `422` | The request is wrong. | Correct it as `fix` says, then retry. |
| [`authentication_error`](#authentication-error) | `401` | Credentials are missing, malformed or not accepted. | Send a valid API key. |
| [`permission_error`](#permission-error) | `400`, `403` | The credentials are valid but not allowed, for example a revoked key or a private URL. | Don't retry. Follow `fix`, or ask a human. |
| [`billing_error`](#billing-error) | `402`, `451` | Out of funds, or a pay-per-request payment is needed or failed. | Don't retry unchanged. Top up or pay. |
| [`rate_limit_error`](#rate-limit-error) | `400`, `429` | Too many requests, to your limit or to a Keenable service. | Wait `retry_after_seconds`, then retry. |
| [`target_error`](#target-error) | [Fetch target codes](#fetch-target-codes) | The page being fetched failed, not Keenable. | Retry if `retryable`, otherwise fetch another source. |
| [`api_error`](#api-error) | `422`, `5xx`, `529` | Something failed on Keenable's side. | Retry with backoff, then [report it](#report-a-problem). |

## Retry rules

Decide whether to retry from the response's `retryable` field, not from the status. On the MCP endpoint it's `error.data.retryable` in the JSON-RPC error. A `5xx` can be final, such as `select_timeout`, and a `4xx` can be worth repeating, such as `domain_record_missing`. The tables under [Error codes](#error-codes) show the usual value for each code.

| Response | What to do |
| - | - |
| `"retryable": true` | Wait `retry_after_seconds`, then send the same request again. The `Retry-After` header carries the same value. |
| `"retryable": false` | Don't send the same request again. Change it or act as `fix` says. |
| No `retryable` field | Retry `408`, `429`, any `5xx` and connection failures, waiting longer before each attempt. Don't retry any other `4xx`, except the device login polls in the next row. This covers a non-JSON body, such as an error page from a proxy in front of the API. |
| `authorization_pending` or `slow_down` | These device login answers follow RFC 8628 and have no `retryable` field. The tables mark them Poll. Keep polling every `interval` seconds, and use the new, longer `interval` after `slow_down`. See [Device login](https://docs.keenable.ai/authentication.md#device-login). |

Sending the same request again can repeat a write that already went through. For a monitor create, send an `Idempotency-Key` and reuse it on the retry, so a create that went through isn't made twice. See [Create a monitor](https://docs.keenable.ai/products/monitors#create-a-monitor). A [pay-per-request](https://docs.keenable.ai/pay-per-request.md) call needs a new signature for each attempt, so after a connection failure a retry can pay a second time if the first payment settled. See [What is charged](https://docs.keenable.ai/pay-per-request.md#what-is-charged).

Every error with `"retryable": true` carries `retry_after_seconds` and a matching `Retry-After` header. When `fix` names a number of attempts, such as once or up to 3 times, stop after that many and [report it](#report-a-problem). Some waits are long: after `public_rate_limit_hourly`, `Retry-After` can be up to an hour.

The [SDKs](https://docs.keenable.ai/sdks.md) retry for you, up to 2 times by default. Monitor `update`, `pause`, `resume`, `trigger` and `bulk` are retried only after a `429`. They wait `Retry-After` when the API sends it, and otherwise back off from 0.5 seconds, doubling up to 8 seconds, with jitter. A `Retry-After` over 60 seconds isn't waited out: the SDK raises the error at once. Set `max_retries` (Python), `maxRetries` (TypeScript), `MaxRetries` (Go) or `max_retries` (Rust) to change the count, or to `0` to turn retries off.

## Error codes

The tables list every code by [type](#error-types), with its status, whether a retry helps and its usual `error`. After them, each code has its own section, with what happened and the fix. The section's anchor is the code with `_` replaced by `-`, which is where `docs_url` points.

The `fix` in a response can be more specific than the text here, for example naming the parameter that failed. The `error` shown is the usual title for the code. A few paths send an older one, such as `Missing authentication` for `missing_api_key`. Device login polls put the RFC 8628 string in `error` instead, such as `expired_token` for `device_code_expired`.

The status sections after the codes, such as [402 Out of funds](#402), show full example bodies and the SDK errors. Older `docs_url` values link to those sections, so their anchors stay.

### `invalid_request_error`

The request is wrong. 41 codes, 1 retryable.

| Code | Status | Retryable | `error` |
| - | - | - | - |
| [`authorization_pending`](#authorization-pending) | `400` | Poll | authorization\_pending |
| [`device_code_already_used`](#device-code-already-used) | `400` | No | Device code already used |
| [`device_code_client_mismatch`](#device-code-client-mismatch) | `400` | No | Wrong client for this code |
| [`device_code_expired`](#device-code-expired) | `400` | No | Device code expired |
| [`invalid_json`](#invalid-json) | `400` | No | Invalid JSON |
| [`invalid_parameter`](#invalid-parameter) | `400` | No | Invalid parameter |
| [`invalid_request`](#invalid-request) | `400` | No | Invalid request |
| [`mcp_message_too_complex`](#mcp-message-too-complex) | `400` | No | MCP message too complex |
| [`missing_app_title`](#missing-app-title) | `400` | No | Missing app identifier |
| [`missing_parameter`](#missing-parameter) | `400` | No | Missing required parameter |
| [`monitor_option_not_supported`](#monitor-option-not-supported) | `400` | No | Monitor option not supported |
| [`query_rejected`](#query-rejected) | `400` | No | Query refused |
| [`search_rejected_upstream`](#search-rejected-upstream) | `400` | No | Search refused |
| [`select_query_failed`](#select-query-failed) | `400` | No | SELECT query failed |
| [`select_query_invalid`](#select-query-invalid) | `400` | No | Invalid SELECT query |
| [`unknown_parameter`](#unknown-parameter) | `400` | No | Bad request |
| [`unknown_tool`](#unknown-tool) | `400` | No | Unknown tool |
| [`unsupported_grant_type`](#unsupported-grant-type) | `400` | No | Unsupported grant type |
| [`user_code_used`](#user-code-used) | `400` | No | Login code already used |
| [`zdr_prompt_unsupported`](#zdr-prompt-unsupported) | `400` | No | zdr\_prompt\_unsupported |
| [`zdr_unsupported_profile`](#zdr-unsupported-profile) | `400` | No | zdr\_unsupported\_profile |
| [`card_expired`](#card-expired) | `404` | No | Card expired |
| [`card_not_found`](#card-not-found) | `404` | No | Card not found |
| [`internal_route_not_public`](#internal-route-not-public) | `404` | No | Not a public path |
| [`invalid_or_expired_promo_code`](#invalid-or-expired-promo-code) | `404` | No | Unknown promo code |
| [`not_found`](#not-found) | `404` | No | Not found |
| [`route_not_found`](#route-not-found) | `404` | No | No such endpoint |
| [`user_code_not_found`](#user-code-not-found) | `404` | No | Login code not found |
| [`version_not_found`](#version-not-found) | `404` | No | No stored version |
| [`method_not_allowed`](#method-not-allowed) | `405` | No | Method not allowed |
| [`mcp_not_acceptable`](#mcp-not-acceptable) | `406` | No | Accept header not supported |
| [`domain_taken`](#domain-taken) | `409` | No | Domain already verified |
| [`idempotency_conflict`](#idempotency-conflict) | `409` | No | Idempotency key reused |
| [`last_admin`](#last-admin) | `409` | No | Last admin |
| [`no_active_organization`](#no-active-organization) | `409` | No | No active organization |
| [`remove_self`](#remove-self) | `409` | No | Cannot remove yourself |
| [`request_rejected`](#request-rejected) | `409` | No | Request rejected |
| [`request_too_large`](#request-too-large) | `413` | No | Request body too large |
| [`unsupported_content_encoding`](#unsupported-content-encoding) | `415` | No | Unsupported body encoding |
| [`domain_record_missing`](#domain-record-missing) | `422` | Yes | Verification record not found |
| [`unprocessable`](#unprocessable) | `422` | No | Unprocessable entity |

### `authentication_error`

Credentials are missing, malformed or not accepted. 15 codes, 0 retryable.

| Code | Status | Retryable | `error` |
| - | - | - | - |
| [`api_key_required`](#api-key-required) | `401` | No | API key required |
| [`invalid_api_key`](#invalid-api-key) | `401` | No | Authentication failed |
| [`invalid_authorization_header`](#invalid-authorization-header) | `401` | No | Malformed Authorization header |
| [`invalid_bearer_token`](#invalid-bearer-token) | `401` | No | Authentication failed |
| [`invalid_session_token`](#invalid-session-token) | `401` | No | Session not accepted |
| [`missing_api_key`](#missing-api-key) | `401` | No | Missing API key |
| [`missing_session_token`](#missing-session-token) | `401` | No | Sign-in required |
| [`sign_in_required`](#sign-in-required) | `401` | No | Sign-in required |
| [`unauthenticated`](#unauthenticated) | `401` | No | Authentication required |
| [`zeroclick_request_id_missing`](#zeroclick-request-id-missing) | `401` | No | ZeroClick request id missing |
| [`zeroclick_signature_expired`](#zeroclick-signature-expired) | `401` | No | ZeroClick signature expired |
| [`zeroclick_signature_invalid`](#zeroclick-signature-invalid) | `401` | No | ZeroClick signature invalid |
| [`zeroclick_signature_malformed`](#zeroclick-signature-malformed) | `401` | No | ZeroClick signature malformed |
| [`zeroclick_signature_missing`](#zeroclick-signature-missing) | `401` | No | ZeroClick signature missing |
| [`zeroclick_signing_key_unknown`](#zeroclick-signing-key-unknown) | `401` | No | ZeroClick signing key unknown |

### `permission_error`

The credentials are valid but not allowed. 17 codes, 0 retryable.

| Code | Status | Retryable | `error` |
| - | - | - | - |
| [`device_code_denied`](#device-code-denied) | `400` | No | Login declined |
| [`admin_required`](#admin-required) | `403` | No | Admin required |
| [`company_email_required`](#company-email-required) | `403` | No | Company address required |
| [`credentials_forbidden`](#credentials-forbidden) | `403` | No | Forbidden |
| [`forbidden`](#forbidden) | `403` | No | Forbidden |
| [`mcp_host_not_allowed`](#mcp-host-not-allowed) | `403` | No | Host not allowed |
| [`mcp_origin_not_allowed`](#mcp-origin-not-allowed) | `403` | No | Origin not allowed |
| [`member_roles_not_enabled`](#member-roles-not-enabled) | `403` | No | Roles not enabled |
| [`mode_requires_api_key`](#mode-requires-api-key) | `403` | No | Mode needs an API key |
| [`monitor_limit_reached`](#monitor-limit-reached) | `403` | No | Active monitor limit reached |
| [`monitors_not_enabled`](#monitors-not-enabled) | `403` | No | Monitors not enabled |
| [`private_url_not_allowed`](#private-url-not-allowed) | `403` | No | Forbidden |
| [`promo_card_required`](#promo-card-required) | `403` | No | Card required |
| [`promo_card_reused`](#promo-card-reused) | `403` | No | Card already used |
| [`promo_code_not_active`](#promo-code-not-active) | `403` | No | Promo code not active |
| [`promo_new_accounts_only`](#promo-new-accounts-only) | `403` | No | Promo code is for new accounts |
| [`time_machine_not_enabled`](#time-machine-not-enabled) | `403` | No | Time Machine not enabled |

### `billing_error`

Out of funds, or a pay-per-request payment is needed or failed. 6 codes, 0 retryable.

| Code | Status | Retryable | `error` |
| - | - | - | - |
| [`insufficient_credits`](#insufficient-credits) | `402` | No | Insufficient credits |
| [`payment_rejected`](#payment-rejected) | `402` | No | Payment rejected |
| [`payment_required`](#payment-required) | `402` | No | Payment required |
| [`payment_settlement_failed`](#payment-settlement-failed) | `402` | No | Payment settlement failed |
| [`zeroclick_allowance_denied`](#zeroclick-allowance-denied) | `402` | No | ZeroClick allowance denied |
| [`payments_region_unavailable`](#payments-region-unavailable) | `451` | No | Unavailable for legal reasons |

### `rate_limit_error`

Too many requests, to your limit or to a Keenable service. 11 codes, 9 retryable.

| Code | Status | Retryable | `error` |
| - | - | - | - |
| [`slow_down`](#slow-down) | `400` | Poll | slow\_down |
| [`fetch_rate_limited`](#fetch-rate-limited) | `429` | Yes | Rate limit exceeded |
| [`paid_rate_limit_per_second`](#paid-rate-limit-per-second) | `429` | Yes | Rate limit exceeded |
| [`public_domain_requires_api_key`](#public-domain-requires-api-key) | `429` | No | API key required for this site |
| [`public_rate_limit_domain`](#public-rate-limit-domain) | `429` | Yes | Rate limit exceeded |
| [`public_rate_limit_hourly`](#public-rate-limit-hourly) | `429` | Yes | Rate limit exceeded |
| [`public_rate_limit_per_second`](#public-rate-limit-per-second) | `429` | Yes | Rate limit exceeded |
| [`rate_limit_per_second`](#rate-limit-per-second) | `429` | Yes | Rate limit exceeded |
| [`rate_limited`](#rate-limited) | `429` | Yes | Rate limit exceeded |
| [`search_rate_limited`](#search-rate-limited) | `429` | Yes | Rate limit exceeded |
| [`select_concurrency_limited`](#select-concurrency-limited) | `429` | Yes | Too many queries running |

### `target_error`

The page being fetched failed, not Keenable. 9 codes, 3 retryable.

| Code | Status | Retryable | `error` |
| - | - | - | - |
| [`target_blocked`](#target-blocked) | `403` | No | Upstream forbidden |
| [`page_not_found`](#page-not-found) | `404` | No | Not found |
| [`content_not_extracted`](#content-not-extracted) | `422` | No | Unprocessable entity |
| [`target_http_error`](#target-http-error) | `422` | No | Unprocessable entity |
| [`target_paywalled`](#target-paywalled) | `422` | No | Unprocessable entity |
| [`target_wrong_page`](#target-wrong-page) | `422` | No | Unprocessable entity |
| [`target_rate_limited`](#target-rate-limited) | `429` | Yes | Rate limit exceeded |
| [`target_unreachable`](#target-unreachable) | `502` | Yes | Bad gateway |
| [`target_timeout`](#target-timeout) | `504` | Yes | Gateway timeout |

### `api_error`

Something failed on Keenable's side. 24 codes, 19 retryable.

| Code | Status | Retryable | `error` |
| - | - | - | - |
| [`dns_lookup_failed`](#dns-lookup-failed) | `422` | Yes | DNS lookup failed |
| [`search_failed_upstream`](#search-failed-upstream) | `422` | Yes | Search failed |
| [`auth_internal_error`](#auth-internal-error) | `500` | Yes | Authentication service error |
| [`balance_check_unavailable`](#balance-check-unavailable) | `500` | Yes | Balance check failed |
| [`billing_account_not_found`](#billing-account-not-found) | `500` | No | Billing record missing |
| [`card_too_large`](#card-too-large) | `500` | No | Card too large |
| [`fetch_mode_unavailable`](#fetch-mode-unavailable) | `500` | Yes | Fetch mode unavailable |
| [`fetcher_unavailable`](#fetcher-unavailable) | `500` | Yes | Fetcher unavailable |
| [`internal_error`](#internal-error) | `500` | Yes | Internal server error |
| [`search_upstream_error`](#search-upstream-error) | `500` | Yes | Search backend failed |
| [`payment_facilitator_error`](#payment-facilitator-error) | `502` | Yes | Bad gateway |
| [`payment_verification_unavailable`](#payment-verification-unavailable) | `502` | Yes | Payment verification failed |
| [`select_disabled`](#select-disabled) | `502` | No | SELECT switched off |
| [`select_internal_error`](#select-internal-error) | `502` | Yes | SELECT failed |
| [`select_timeout`](#select-timeout) | `502` | No | SELECT timed out |
| [`select_unavailable`](#select-unavailable) | `502` | Yes | SELECT unavailable |
| [`allowance_unavailable`](#allowance-unavailable) | `503` | Yes | Allowance check unavailable |
| [`auth_unavailable`](#auth-unavailable) | `503` | Yes | Authentication temporarily unavailable |
| [`card_storage_unavailable`](#card-storage-unavailable) | `503` | Yes | Card storage unavailable |
| [`device_login_unavailable`](#device-login-unavailable) | `503` | Yes | Device login unavailable |
| [`monitors_unavailable`](#monitors-unavailable) | `503` | Yes | Monitors temporarily unavailable |
| [`payments_unavailable`](#payments-unavailable) | `503` | Yes | Payments temporarily unavailable |
| [`service_not_configured`](#service-not-configured) | `503` | No | Not configured |
| [`search_overloaded`](#search-overloaded) | `529` | Yes | Overloaded |

### Authentication codes

Missing, malformed, unknown or revoked credentials.

#### `admin_required`

* **Status:** `403`
* **Type:** [`permission_error`](#error-types)
* **`error`:** `Admin required`
* **Retryable:** No
* **What happened:** Only an admin of this organization can do this; the caller is a member.
* **How to fix:** Only an admin of this organization can do this, and this account is a member. Ask an admin (Team page in the console) to do it or to make this account an admin. Retrying from this account returns the same 403.

#### `api_key_required`

* **Status:** `401`
* **Type:** [`authentication_error`](#error-types)
* **`error`:** `API key required`
* **Retryable:** No
* **What happened:** This endpoint takes a Keenable API key, and the request sent only a session token.
* **How to fix:** This endpoint takes a Keenable API key, not a console session token. Send the key in the X-API-Key header and retry. Create one at [https://app.keenable.ai/console/api-keys](https://app.keenable.ai/console/api-keys).

#### `auth_unavailable`

* **Status:** `503`
* **Type:** [`api_error`](#error-types)
* **`error`:** `Authentication temporarily unavailable`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** Keenable could not check the credentials just now.
* **How to fix:** Keenable could not check your credentials just now; the key itself may be fine. Wait for Retry-After and retry the same request.
* **More:** [5xx Server error](#5xx)

#### `company_email_required`

* **Status:** `403`
* **Type:** [`permission_error`](#error-types)
* **`error`:** `Company address required`
* **Retryable:** No
* **What happened:** Only an account signed up with a company email address can verify its domain.
* **How to fix:** Domain verification needs an account signed up with a company email address (not a personal mailbox such as gmail.com). Ask a colleague who signed up with the company address to verify it. Retrying from this account returns the same 403.

#### `credentials_forbidden`

* **Status:** `403`
* **Type:** [`permission_error`](#error-types)
* **`error`:** `Forbidden`
* **Retryable:** No
* **What happened:** The credentials were recognized but are not allowed, usually because the key was revoked.
* **How to fix:** The credentials were recognized but are not allowed, usually because the key was revoked. Retrying with them will not help: create a new key at [https://app.keenable.ai/console/api-keys](https://app.keenable.ai/console/api-keys), or ask a human with console access to create one for you.
* **More:** [403 Key rejected or revoked](#403)

#### `device_code_denied`

* **Status:** `400`
* **Type:** [`permission_error`](#error-types)
* **`error`:** `Login declined`
* **Retryable:** No
* **What happened:** The user declined this device login.
* **How to fix:** Ask the user whether to try again before you request a new code.

#### `invalid_api_key`

* **Status:** `401`
* **Type:** [`authentication_error`](#error-types)
* **`error`:** `Authentication failed`
* **Retryable:** No
* **What happened:** The API key is malformed, unknown or expired.
* **How to fix:** The API key was not accepted. Copy the full key from [https://app.keenable.ai/console/api-keys](https://app.keenable.ai/console/api-keys), or create a new one there, and retry with it in the X-API-Key header.
* **More:** [401 Invalid key](#401-invalid-key)

#### `invalid_authorization_header`

* **Status:** `401`
* **Type:** [`authentication_error`](#error-types)
* **`error`:** `Malformed Authorization header`
* **Retryable:** No
* **What happened:** The Authorization header is present but is not "Bearer \<token>".
* **How to fix:** Send the credential as "Authorization: Bearer \<token>", or send a Keenable API key in the X-API-Key header (create one at [https://app.keenable.ai/console/api-keys](https://app.keenable.ai/console/api-keys)), and retry.

#### `invalid_bearer_token`

* **Status:** `401`
* **Type:** [`authentication_error`](#error-types)
* **`error`:** `Authentication failed`
* **Retryable:** No
* **What happened:** The bearer token is malformed or expired.
* **How to fix:** The bearer token was not accepted. Sign in again for a fresh token, or send a Keenable API key from [https://app.keenable.ai/console/api-keys](https://app.keenable.ai/console/api-keys) in the X-API-Key header.
* **More:** [401 Invalid token](#401-invalid-token)

#### `invalid_session_token`

* **Status:** `401`
* **Type:** [`authentication_error`](#error-types)
* **`error`:** `Session not accepted`
* **Retryable:** No
* **What happened:** The session token on a console endpoint is malformed, unknown or expired.
* **How to fix:** The session token was not accepted. Sign in again at [https://app.keenable.ai/console](https://app.keenable.ai/console) for a fresh token and retry. API keys do not work on console endpoints.

#### `mcp_host_not_allowed`

* **Status:** `403`
* **Type:** [`permission_error`](#error-types)
* **`error`:** `Host not allowed`
* **Retryable:** No
* **What happened:** The MCP request carried a Host header this server does not answer for.
* **How to fix:** Connect to the MCP server at its public address (for example [https://api.keenable.ai/mcp](https://api.keenable.ai/mcp)) so the Host header matches, and retry.

#### `mcp_origin_not_allowed`

* **Status:** `403`
* **Type:** [`permission_error`](#error-types)
* **`error`:** `Origin not allowed`
* **Retryable:** No
* **What happened:** The MCP request came from a browser Origin that is not allowed, or carried several Origin headers.
* **How to fix:** Call the MCP server from an MCP client or a server, not from a web page on another origin, and send at most one Origin header.

#### `member_roles_not_enabled`

* **Status:** `403`
* **Type:** [`permission_error`](#error-types)
* **`error`:** `Roles not enabled`
* **Retryable:** No
* **What happened:** Admin and member roles are not turned on for this organization.
* **How to fix:** Admin and member roles are not turned on for this organization, so everyone in it can already do everything. Contact us to turn them on.

#### `missing_api_key`

* **Status:** `401`
* **Type:** [`authentication_error`](#error-types)
* **`error`:** `Missing API key`
* **Retryable:** No
* **What happened:** The request carried no API key or bearer token.
* **How to fix:** Send your Keenable API key in the X-API-Key header (or as "Authorization: Bearer \<key>") and retry. Create a key at [https://app.keenable.ai/console/api-keys](https://app.keenable.ai/console/api-keys).
* **More:** [401 Missing key](#401-missing-key)

#### `missing_session_token`

* **Status:** `401`
* **Type:** [`authentication_error`](#error-types)
* **`error`:** `Sign-in required`
* **Retryable:** No
* **What happened:** A console endpoint was called without a signed-in session token.
* **How to fix:** This console endpoint needs a signed-in session: send the session access token as "Authorization: Bearer \<token>". API keys do not work here; sign in at [https://app.keenable.ai/console](https://app.keenable.ai/console) for a token.

#### `mode_requires_api_key`

* **Status:** `403`
* **Type:** [`permission_error`](#error-types)
* **`error`:** `Mode needs an API key`
* **Retryable:** No
* **What happened:** The requested search mode works only with an API key or a signed-in user.
* **How to fix:** This search mode works only with an API key. Send a key in the X-API-Key header (create one at [https://app.keenable.ai/console/api-keys](https://app.keenable.ai/console/api-keys)) on /v1/search, or drop "mode" (or set it to "pro" or "realtime") and retry.

#### `monitor_limit_reached`

* **Status:** `403`
* **Type:** [`permission_error`](#error-types)
* **`error`:** `Active monitor limit reached`
* **Retryable:** No
* **What happened:** The organization already has the most active monitors it may have.
* **How to fix:** The organization already has the most active monitors it may have; the message gives the limit. Pause or delete a monitor (PATCH status "paused", or DELETE), then retry.

#### `monitors_not_enabled`

* **Status:** `403`
* **Type:** [`permission_error`](#error-types)
* **`error`:** `Monitors not enabled`
* **Retryable:** No
* **What happened:** Monitors is turned off for this organization.
* **How to fix:** Monitors is turned off for this organization. Contact [support@keenable.ai](mailto:support@keenable.ai) to turn it on. Retrying returns the same 403.

#### `promo_card_required`

* **Status:** `403`
* **Type:** [`permission_error`](#error-types)
* **`error`:** `Card required`
* **Retryable:** No
* **What happened:** The promo code needs a card on file; details.checkoutUrl is where to save one.
* **How to fix:** Save a card at details.checkoutUrl. The credits are added once the card is saved, and nothing is charged.

#### `promo_card_reused`

* **Status:** `403`
* **Type:** [`permission_error`](#error-types)
* **`error`:** `Card already used`
* **Retryable:** No
* **What happened:** The card on file already redeemed this promo code.
* **How to fix:** Each card can redeem a promo code once, to stop credit farming. Save a card that has not redeemed this code, then retry.

#### `promo_code_not_active`

* **Status:** `403`
* **Type:** [`permission_error`](#error-types)
* **`error`:** `Promo code not active`
* **Retryable:** No
* **What happened:** The promo code exists but is outside the dates it can be redeemed.
* **How to fix:** This promo code can only be redeemed within its dates, and now is outside them; "message" says whether it is not active yet or has expired. Retrying now returns the same 403.

#### `promo_new_accounts_only`

* **Status:** `403`
* **Type:** [`permission_error`](#error-types)
* **`error`:** `Promo code is for new accounts`
* **Retryable:** No
* **What happened:** The promo code works only on accounts created in the last 24 hours.
* **How to fix:** This code works only on accounts created in the last 24 hours, and this account is older. Retrying gives the same answer.

#### `sign_in_required`

* **Status:** `401`
* **Type:** [`authentication_error`](#error-types)
* **`error`:** `Sign-in required`
* **Retryable:** No
* **What happened:** This MCP endpoint, or the WebQL mode requested on it, needs a signed-in user or an API key.
* **How to fix:** Connect with OAuth sign-in, or send a Keenable API key in the X-API-Key header (create one at [https://app.keenable.ai/console/api-keys](https://app.keenable.ai/console/api-keys)), and retry. Keyless MCP works on the default endpoint without WebQL mode.

#### `time_machine_not_enabled`

* **Status:** `403`
* **Type:** [`permission_error`](#error-types)
* **`error`:** `Time Machine not enabled`
* **Retryable:** No
* **What happened:** The request used Time Machine (query\_time), which is not enabled for the organization.
* **How to fix:** Time Machine is not enabled for your organization, so retrying returns the same 403. To use it, contact Keenable support at [support@keenable.ai](mailto:support@keenable.ai) and ask them to enable Time Machine for your organization; include the request\_id from this response. For current results meanwhile, drop query\_time and call /v1/search or /v1/fetch.

#### `zeroclick_request_id_missing`

* **Status:** `401`
* **Type:** [`authentication_error`](#error-types)
* **`error`:** `ZeroClick request id missing`
* **Retryable:** No
* **What happened:** A signed ZeroClick call has no zc-request-id header.
* **How to fix:** Send the zc-request-id that ZeroClick issued for this call, include it in the signature, and resend.

#### `zeroclick_signature_expired`

* **Status:** `401`
* **Type:** [`authentication_error`](#error-types)
* **`error`:** `ZeroClick signature expired`
* **Retryable:** No
* **What happened:** The zc-signature timestamp is too far from the server clock.
* **How to fix:** Sign the request again with the current time and resend it. If it repeats, the signer's clock is off: sync it with NTP.

#### `zeroclick_signature_invalid`

* **Status:** `401`
* **Type:** [`authentication_error`](#error-types)
* **`error`:** `ZeroClick signature invalid`
* **Retryable:** No
* **What happened:** The zc-signature does not match the request that was sent.
* **How to fix:** Sign the exact method, path, body, request id and agent id you send, and resend. A proxy that rewrites the path or the body breaks the signature.

#### `zeroclick_signature_malformed`

* **Status:** `401`
* **Type:** [`authentication_error`](#error-types)
* **`error`:** `ZeroClick signature malformed`
* **Retryable:** No
* **What happened:** The zc-signature header does not parse as t=\<unix seconds>,kid=\<key id>,v1=\<64 hex>.
* **How to fix:** ZeroClick builds this header. Rebuild it as t=\<unix seconds>,kid=\<key id>,v1=\<64 lowercase hex>, or, if you called through ZeroClick, report it to ZeroClick with the request\_id.

#### `zeroclick_signature_missing`

* **Status:** `401`
* **Type:** [`authentication_error`](#error-types)
* **`error`:** `ZeroClick signature missing`
* **Retryable:** No
* **What happened:** A ZeroClick path was called without the zc-signature header.
* **How to fix:** This path accepts only calls that ZeroClick signs and forwards. Buy and call it through ZeroClick; to pay per request with a wallet use /v1/x402/\*, or use an API key ([https://app.keenable.ai/console/api-keys](https://app.keenable.ai/console/api-keys)) on /v1/search and /v1/fetch.

#### `zeroclick_signing_key_unknown`

* **Status:** `401`
* **Type:** [`authentication_error`](#error-types)
* **`error`:** `ZeroClick signing key unknown`
* **Retryable:** No
* **What happened:** The zc-signature names a key id Keenable does not hold.
* **How to fix:** Sign with a current ZeroClick signing key. After a key rotation, ask Keenable to load the new key, then retry.

### Validation codes

The request itself is wrong. Correct it as `fix` says; sending it again unchanged returns the same error.

#### `authorization_pending`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `authorization_pending`
* **Retryable:** Poll again after `interval` seconds. The body has no `retryable` field.
* **What happened:** The user has not approved this device login yet; "interval" is how long to wait before polling again.
* **How to fix:** Poll again after the number of seconds in "interval". Keep showing the user the user\_code and verification\_uri.

#### `card_expired`

* **Status:** `404`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Card expired`
* **Retryable:** No
* **What happened:** The card at this address has expired and was deleted.
* **How to fix:** The card expired and is gone for good, so retrying returns the same 404. Run the search again for a fresh card.

#### `card_not_found`

* **Status:** `404`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Card not found`
* **Retryable:** No
* **What happened:** No card exists at this address.
* **How to fix:** No card exists at this address. Check that the link is complete and copied exactly. Retrying the same link returns the same 404.

#### `device_code_already_used`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Device code already used`
* **Retryable:** No
* **What happened:** The device code was already exchanged for an API key; each code works once.
* **How to fix:** Use the API key from the first successful poll. If you lost it, revoke it in the console and request a new code with POST /v1/auth/agent/code.

#### `device_code_client_mismatch`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Wrong client for this code`
* **Retryable:** No
* **What happened:** The device code was issued to a different client\_id.
* **How to fix:** Poll with the same client\_id you sent to POST /v1/auth/agent/code.

#### `device_code_expired`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Device code expired`
* **Retryable:** No
* **What happened:** The device code expired or was never issued.
* **How to fix:** Request a new code with POST /v1/auth/agent/code and show the user the new user\_code.

#### `domain_record_missing`

* **Status:** `422`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Verification record not found`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The domain does not publish the Keenable verification TXT record yet.
* **How to fix:** Publish the TXT record named in "message" on the domain, wait for Retry-After (DNS changes can take a few minutes to show up), then verify again.

#### `domain_taken`

* **Status:** `409`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Domain already verified`
* **Retryable:** No
* **What happened:** Another Keenable organization already verified this domain.
* **How to fix:** Another Keenable organization already verified this domain, so this one cannot. Ask a colleague to invite you to that organization, or contact us with the request\_id if the domain is yours.

#### `idempotency_conflict`

* **Status:** `409`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Idempotency key reused`
* **Retryable:** No
* **What happened:** The Idempotency-Key was already used with a different request body.
* **How to fix:** This Idempotency-Key was already used with a different request body. Send a new key for a new request, or resend the original body to get the original result.

#### `internal_route_not_public`

* **Status:** `404`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Not a public path`
* **Retryable:** No
* **What happened:** Paths under /internal/ are not served on the public API; the load balancer answers this itself.
* **How to fix:** Use the public API under /v1 instead.

#### `invalid_json`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Invalid JSON`
* **Retryable:** No
* **What happened:** The request body is not valid JSON.
* **How to fix:** The request body could not be parsed as JSON. Send a valid JSON object with Content-Type: application/json (check quoting and trailing commas), or send the parameters in the query string, and retry.

#### `invalid_or_expired_promo_code`

* **Status:** `404`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Unknown promo code`
* **Retryable:** No
* **What happened:** No promo code with this name exists.
* **How to fix:** Check the spelling with whoever gave you the code. Retrying the same code returns the same 404.

#### `invalid_parameter`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Invalid parameter`
* **Retryable:** No
* **What happened:** A parameter has a value the endpoint does not accept; "param" names it.
* **How to fix:** Correct the parameter named in "param" and retry; the API reference lists the values it accepts.
* **More:** [400 Invalid request parameters](#400-invalid-request)

#### `invalid_request`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Invalid request`
* **Retryable:** No
* **What happened:** The request did not match the schema, or was rejected as invalid.
* **How to fix:** Read "message" for what to change, and "details", when present, for each field that failed; correct the request and retry.
* **More:** [400 Invalid request parameters](#400-invalid-request)

#### `last_admin`

* **Status:** `409`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Last admin`
* **Retryable:** No
* **What happened:** The change would leave the organization without an admin.
* **How to fix:** An organization always keeps at least one admin, and this change would remove the last one. Make someone else an admin first, then retry.

#### `mcp_message_too_complex`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `MCP message too complex`
* **Retryable:** No
* **What happened:** The JSON-RPC message nests too deeply, has too many values or an array that is too long.
* **How to fix:** Send a smaller JSON-RPC message: at most 64 levels deep, 50,000 values and 1,000 items per array.

#### `mcp_not_acceptable`

* **Status:** `406`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Accept header not supported`
* **Retryable:** No
* **What happened:** The MCP request did not accept both application/json and text/event-stream.
* **How to fix:** Send the header "Accept: application/json, text/event-stream" (the Streamable HTTP transport needs both) and retry.

#### `method_not_allowed`

* **Status:** `405`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Method not allowed`
* **Retryable:** No
* **What happened:** The path exists but does not accept this HTTP method; the Allow header and "allowed" list the ones it does.
* **How to fix:** Send the request again with one of the methods listed in "allowed" (also in the Allow header).

#### `missing_app_title`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Missing app identifier`
* **Retryable:** No
* **What happened:** A keyless request did not name its app.
* **How to fix:** Name your app in the X-Keenable-Title header (or the keenable\_title query parameter) and retry. With an API key, call /v1/search or /v1/fetch instead, which do not need it.
* **More:** [400 Missing app identifier](#400-missing-app-identifier)

#### `missing_parameter`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Missing required parameter`
* **Retryable:** No
* **What happened:** A required parameter is missing; "param" names it.
* **How to fix:** Send the parameter named in "param"; it is required. Then retry.
* **More:** [400 Invalid request parameters](#400-invalid-request)

#### `monitor_option_not_supported`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Monitor option not supported`
* **Retryable:** No
* **What happened:** The monitor request uses an option Monitors does not offer yet; the message names it.
* **How to fix:** The monitor request uses an option Monitors does not offer yet: read "message" for its name, remove it and retry. Retrying unchanged returns the same 400.

#### `no_active_organization`

* **Status:** `409`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `No active organization`
* **Retryable:** No
* **What happened:** The signed-in account has no active organization to bill.
* **How to fix:** This account is signed in but has no active organization, so there is nothing to bill. Create or join an organization at [https://app.keenable.ai/console](https://app.keenable.ai/console), or call with an API key, then retry.

#### `query_rejected`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Query refused`
* **Retryable:** No
* **What happened:** The query broke a traffic rule; "message" says which.
* **How to fix:** Read "message" for the limit the query broke, change the query and retry. Sending it unchanged returns the same 400.

#### `remove_self`

* **Status:** `409`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Cannot remove yourself`
* **Retryable:** No
* **What happened:** An admin tried to remove their own account from the organization.
* **How to fix:** An admin cannot remove their own account. Ask another admin to remove it.

#### `request_too_large`

* **Status:** `413`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Request body too large`
* **Retryable:** No
* **What happened:** The JSON request body is larger than the server accepts.
* **How to fix:** The JSON request body is larger than the server accepts. Send only the documented parameters, with a shorter query, and retry.
* **More:** [400 Invalid request parameters](#400-invalid-request)

#### `route_not_found`

* **Status:** `404`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `No such endpoint`
* **Retryable:** No
* **What happened:** No endpoint is served at this path.
* **How to fix:** No endpoint is served at this path. Check the path against the API reference at [https://docs.keenable.ai/api-reference](https://docs.keenable.ai/api-reference.md) (for example /v1/search or /v1/fetch) and retry.

#### `search_rejected_upstream`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Search refused`
* **Retryable:** No
* **What happened:** The search backend refused the request; "message" carries its reason.
* **How to fix:** Our search backend refused this request; "message" has its reason. Change the query or the filter it names and retry. Sending it unchanged returns the same 400; if the query looks valid, report it with the request\_id.

#### `select_query_failed`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `SELECT query failed`
* **Retryable:** No
* **What happened:** The query is valid but failed while it ran; "message" has the reason.
* **How to fix:** Nothing was charged. The query failed while it ran (see "message"). Change it, for example narrow WEB\_SEARCH or simplify the extraction, using [https://select.keenable.ai/guide.md](https://select.keenable.ai/guide.md), then send it again.

#### `select_query_invalid`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Invalid SELECT query`
* **Retryable:** No
* **What happened:** SELECT refused the query as invalid; "message" has its reason.
* **How to fix:** Nothing was charged. Fix the query using "message" and the guide at [https://select.keenable.ai/guide.md](https://select.keenable.ai/guide.md), then send it again. Retrying it unchanged returns the same 400.

#### `unknown_parameter`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Bad request`
* **Retryable:** No
* **What happened:** The request has a parameter the endpoint does not know; "allowed" lists the ones it does, and "did\_you\_mean" maps a name that is close to a supported parameter to that parameter.
* **How to fix:** Remove the unknown parameter, or rename it to one of the parameters listed in "allowed", and retry.
* **More:** [400 Invalid request parameters](#400-invalid-request)

#### `unknown_tool`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Unknown tool`
* **Retryable:** No
* **What happened:** The MCP tools/call named a tool this server does not have.
* **How to fix:** Call tools/list for the tools this server offers, and call one of them by its exact name.

#### `unsupported_content_encoding`

* **Status:** `415`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Unsupported body encoding`
* **Retryable:** No
* **What happened:** The request body uses a Content-Encoding or charset the server does not read.
* **How to fix:** Send the JSON body in UTF-8, uncompressed or with gzip, deflate or br Content-Encoding, and retry.

#### `unsupported_grant_type`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Unsupported grant type`
* **Retryable:** No
* **What happened:** The device login poll named a grant\_type other than the device code grant.
* **How to fix:** Send grant\_type=urn:ietf:params:oauth:grant-type:device\_code with your device\_code and client\_id.

#### `user_code_not_found`

* **Status:** `404`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Login code not found`
* **Retryable:** No
* **What happened:** No pending login matches this user\_code; it may be mistyped or expired.
* **How to fix:** Check the code shown by the agent or CLI. If it still fails, run `keenable login` again or ask the agent for a new code.

#### `user_code_used`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Login code already used`
* **Retryable:** No
* **What happened:** This login was already approved.
* **How to fix:** This login was already approved, so the agent or CLI already has its key. To log in again, run `keenable login` again or ask the agent for a new code.

#### `version_not_found`

* **Status:** `404`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `No stored version`
* **Retryable:** No
* **What happened:** Time Machine has no copy of this page at or before query\_time.
* **How to fix:** No copy of this page is stored at or before query\_time. Try a later query\_time, or check that the URL is correct. Retrying the same request returns the same 404.

#### `zdr_prompt_unsupported`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `zdr_prompt_unsupported`
* **Retryable:** No
* **What happened:** The zero data retention policy does not allow fetching with a prompt.
* **How to fix:** This request runs under a zero data retention policy, which does not allow fetching with a prompt. Remove the prompt parameter. Retrying the same request returns the same 400.
* **More:** [400 Invalid request parameters](#400-invalid-request)

#### `zdr_unsupported_profile`

* **Status:** `400`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `zdr_unsupported_profile`
* **Retryable:** No
* **What happened:** The zero data retention policy does not allow the data sources this request needs.
* **How to fix:** This request runs under a zero data retention policy, which does not allow the data sources it needs. Retrying the same request returns the same 400.
* **More:** [400 Invalid request parameters](#400-invalid-request)

### Credits and payment codes

Credits for keyed requests, and payments on the [pay-per-request](https://docs.keenable.ai/pay-per-request.md) paths.

#### `insufficient_credits`

* **Status:** `402`
* **Type:** [`billing_error`](#error-types)
* **`error`:** `Insufficient credits`
* **Retryable:** No
* **What happened:** This month's free requests and the purchased credits are used up.
* **How to fix:** Retrying returns the same 402 until credits are added. Ask a human with console access to buy credits at the URL in this response's billing\_url field (the Billing page of the Keenable console), and to turn on auto top-up there so the balance refills itself ([https://docs.keenable.ai/auto-top-up.md](https://docs.keenable.ai/auto-top-up.md)).
* **More:** [402 Out of credits](#402)

#### `payment_facilitator_error`

* **Status:** `502`
* **Type:** [`api_error`](#error-types)
* **`error`:** `Bad gateway`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The x402 payment facilitator failed while settling.
* **How to fix:** The x402 facilitator failed while settling, so nothing was returned. Wait a few seconds and retry with a new payment.
* **More:** [Pay per request errors](https://docs.keenable.ai/pay-per-request.md#errors)

#### `payment_rejected`

* **Status:** `402`
* **Type:** [`billing_error`](#error-types)
* **`error`:** `Payment rejected`
* **Retryable:** No
* **What happened:** A PAYMENT-SIGNATURE was sent but the payment was not accepted; "reason" says why.
* **How to fix:** Nothing was charged. Read "reason", then sign one of the "accepts" offers exactly as given (scheme, network, asset, amount and payTo) with a funded wallet and resend it in the PAYMENT-SIGNATURE header.

#### `payment_required`

* **Status:** `402`
* **Type:** [`billing_error`](#error-types)
* **`error`:** `Payment required`
* **Retryable:** No
* **What happened:** A pay-per-request endpoint (x402, or ZeroClick on /v1/zeroclick/\*) was called without a payment.
* **How to fix:** Pay and send the same request again: with x402, sign one of the "accepts" offers and retry with the PAYMENT-SIGNATURE header; through ZeroClick, retry as an agent whose allowance covers the usage. Without either, call /v1/search or /v1/fetch with an API key instead.
* **More:** [Pay per request errors](https://docs.keenable.ai/pay-per-request.md#errors)

#### `payment_settlement_failed`

* **Status:** `402`
* **Type:** [`billing_error`](#error-types)
* **`error`:** `Payment settlement failed`
* **Retryable:** No
* **What happened:** The payment was verified but could not be settled, so the result was withheld.
* **How to fix:** Nothing was charged. Sign a new payment for the offer and retry; reusing the same PAYMENT-SIGNATURE fails again.
* **More:** [Pay per request errors](https://docs.keenable.ai/pay-per-request.md#errors)

#### `payments_region_unavailable`

* **Status:** `451`
* **Type:** [`billing_error`](#error-types)
* **`error`:** `Unavailable for legal reasons`
* **Retryable:** No
* **What happened:** Pay-per-request access is not offered in the caller's region.
* **How to fix:** Pay-per-request is not offered in your region, so retrying will not help. Call /v1/search and /v1/fetch with an API key ([https://app.keenable.ai/console/api-keys](https://app.keenable.ai/console/api-keys)) instead.
* **More:** [Pay per request errors](https://docs.keenable.ai/pay-per-request.md#errors)

#### `payments_unavailable`

* **Status:** `503`
* **Type:** [`api_error`](#error-types)
* **`error`:** `Payments temporarily unavailable`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** Pay-per-request access is briefly unavailable.
* **How to fix:** Pay-per-request is briefly unavailable. Wait for Retry-After and retry, or call /v1/search and /v1/fetch with an API key ([https://app.keenable.ai/console/api-keys](https://app.keenable.ai/console/api-keys)).
* **More:** [Pay per request errors](https://docs.keenable.ai/pay-per-request.md#errors)

#### `zeroclick_allowance_denied`

* **Status:** `402`
* **Type:** [`billing_error`](#error-types)
* **`error`:** `ZeroClick allowance denied`
* **Retryable:** No
* **What happened:** ZeroClick did not authorize this agent to pay for the call; "reason" has its reason.
* **How to fix:** Nothing was charged. Top up or raise this agent's allowance on ZeroClick, then retry; ZeroClick's reason is in "reason". Without ZeroClick, use an API key ([https://app.keenable.ai/console/api-keys](https://app.keenable.ai/console/api-keys)) on /v1/search and /v1/fetch.

### Rate limit codes

Your own limits, and Keenable services that are briefly busy. See [Rate limits](https://docs.keenable.ai/rate-limits.md) for every tier.

#### `fetch_rate_limited`

* **Status:** `429`
* **Type:** [`rate_limit_error`](#error-types)
* **`error`:** `Rate limit exceeded`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The fetcher is briefly rate-limited on the Keenable side, not by your own limit.
* **How to fix:** The fetcher is briefly rate-limited on our side; this is not your own limit. Wait for Retry-After and retry.
* **More:** [429 Rate limit exceeded](#429)

#### `paid_rate_limit_per_second`

* **Status:** `429`
* **Type:** [`rate_limit_error`](#error-types)
* **`error`:** `Rate limit exceeded`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The per-second limit on pay-per-request access was exceeded.
* **How to fix:** Wait for Retry-After and retry. For a limit that can be raised, use an API key with prepaid credits ([https://app.keenable.ai/console/api-keys](https://app.keenable.ai/console/api-keys)) on /v1/search and /v1/fetch.
* **More:** [429 Rate limit exceeded](#429)

#### `public_domain_requires_api_key`

* **Status:** `429`
* **Type:** [`rate_limit_error`](#error-types)
* **`error`:** `API key required for this site`
* **Retryable:** No
* **What happened:** Keyless requests that target a restricted site (PUBLIC\_BLOCKED\_REQUEST\_DOMAINS) are not served; they need an API key.
* **How to fix:** Requests that target this site need an API key. Run `keenable login`, or create a free API key at [https://app.keenable.ai/console/api-keys](https://app.keenable.ai/console/api-keys) and call /v1/search or /v1/fetch with it in the X-API-Key header. Retrying without a key returns 429 again. No account yet? Sign up at [https://app.keenable.ai/signup](https://app.keenable.ai/signup): the free API key includes 100,000 requests a month.

#### `public_rate_limit_domain`

* **Status:** `429`
* **Type:** [`rate_limit_error`](#error-types)
* **`error`:** `Rate limit exceeded`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The per-second limit for keyless requests that target a restricted site, shared by every keyless caller, was exceeded.
* **How to fix:** Send an API key (create one at [https://app.keenable.ai/console/api-keys](https://app.keenable.ai/console/api-keys)) to /v1/search or /v1/fetch: keyed requests are not under this limit. Otherwise wait for Retry-After and retry. No account yet? Sign up at [https://app.keenable.ai/signup](https://app.keenable.ai/signup): the free API key includes 100,000 requests a month.

#### `public_rate_limit_hourly`

* **Status:** `429`
* **Type:** [`rate_limit_error`](#error-types)
* **`error`:** `Rate limit exceeded`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The hourly limit for keyless requests from this IP address was reached.
* **How to fix:** Wait for Retry-After (up to an hour) before retrying; a retry sooner returns 429 again. To continue now instead, create a free API key at [https://app.keenable.ai/console/api-keys](https://app.keenable.ai/console/api-keys) and call /v1/search or /v1/fetch with it in the X-API-Key header: keyed requests have no hourly cap. No account yet? Sign up at [https://app.keenable.ai/signup](https://app.keenable.ai/signup): the free API key includes 100,000 requests a month.
* **More:** [429 Rate limit exceeded](#429)

#### `public_rate_limit_per_second`

* **Status:** `429`
* **Type:** [`rate_limit_error`](#error-types)
* **`error`:** `Rate limit exceeded`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The per-second limit for keyless requests from this IP address was exceeded.
* **How to fix:** Wait for Retry-After and retry, or send an API key (create one at [https://app.keenable.ai/console/api-keys](https://app.keenable.ai/console/api-keys)) to /v1/search or /v1/fetch for your organization's own limit. No account yet? Sign up at [https://app.keenable.ai/signup](https://app.keenable.ai/signup): the free API key includes 100,000 requests a month.
* **More:** [429 Rate limit exceeded](#429)

#### `rate_limit_per_second`

* **Status:** `429`
* **Type:** [`rate_limit_error`](#error-types)
* **`error`:** `Rate limit exceeded`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The organization's requests-per-second limit, shared by all its keys, was exceeded.
* **How to fix:** Wait for Retry-After, then retry, and keep under your organization's per-second limit. For a higher limit, upgrade at [https://app.keenable.ai/console/billing?tab=limits](https://app.keenable.ai/console/billing?tab=limits).
* **More:** [429 Rate limit exceeded](#429)

#### `search_overloaded`

* **Status:** `529`
* **Type:** [`api_error`](#error-types)
* **`error`:** `Overloaded`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** Search is briefly overloaded.
* **How to fix:** Search is briefly overloaded. Wait for Retry-After and retry, backing off if it repeats.
* **More:** [5xx Server error](#5xx)

#### `search_rate_limited`

* **Status:** `429`
* **Type:** [`rate_limit_error`](#error-types)
* **`error`:** `Rate limit exceeded`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** Search is briefly rate-limited on the Keenable side, not by your own limit.
* **How to fix:** Search is briefly rate-limited on our side; this is not your own limit. Wait for Retry-After and retry.
* **More:** [429 Rate limit exceeded](#429)

#### `select_concurrency_limited`

* **Status:** `429`
* **Type:** [`rate_limit_error`](#error-types)
* **`error`:** `Too many queries running`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** Too many of this buyer's SELECT queries are running at once.
* **How to fix:** Nothing was charged. Wait for Retry-After, or for one of your running queries to finish, then send the query again.

#### `slow_down`

* **Status:** `400`
* **Type:** [`rate_limit_error`](#error-types)
* **`error`:** `slow_down`
* **Retryable:** Poll again after `interval` seconds. The body has no `retryable` field.
* **What happened:** The device login was polled again before the interval passed; "interval" is the new, longer interval.
* **How to fix:** Wait the number of seconds in "interval" between polls from now on.

### Fetch target codes

These come from fetch, and from search when `query` is a URL. They describe the page you asked for, not your request or your key.

#### `content_not_extracted`

* **Status:** `422`
* **Type:** [`target_error`](#error-types)
* **`error`:** `Unprocessable entity`
* **Retryable:** No
* **What happened:** The page was reached but has no readable text to extract.
* **How to fix:** The page was reached but has no readable text to extract. Retrying will not help: fetch another source.
* **More:** [422 Content could not be extracted](#422)

#### `page_not_found`

* **Status:** `404`
* **Type:** [`target_error`](#error-types)
* **`error`:** `Not found`
* **Retryable:** No
* **What happened:** The site says the page does not exist.
* **How to fix:** The site says the page does not exist. Retrying the same URL returns the same 404: check the URL, or use another search result.
* **More:** [404 Page not found](#404)

#### `private_url_not_allowed`

* **Status:** `403`
* **Type:** [`permission_error`](#error-types)
* **`error`:** `Forbidden`
* **Retryable:** No
* **What happened:** The URL points to a private or non-routable address.
* **How to fix:** The fetcher only reaches public http and https pages. Use a public URL; retrying this one returns the same 403.
* **More:** [403 Key rejected or revoked](#403)

#### `target_blocked`

* **Status:** `403`
* **Type:** [`target_error`](#error-types)
* **`error`:** `Upstream forbidden`
* **Retryable:** No
* **What happened:** The site refused the fetcher, for example with a bot check.
* **How to fix:** The site refused the fetcher, for example with a bot check or an access rule. This is not about your API key, and retrying the same URL will not help: fetch another source for the same content.
* **More:** [422 Content could not be extracted](#422)

#### `target_http_error`

* **Status:** `422`
* **Type:** [`target_error`](#error-types)
* **`error`:** `Unprocessable entity`
* **Retryable:** No
* **What happened:** The site answered with an error status for this URL.
* **How to fix:** The site answered with an error status for this URL. Retrying the same URL will not help: check the URL or fetch another source.
* **More:** [422 Content could not be extracted](#422)

#### `target_paywalled`

* **Status:** `422`
* **Type:** [`target_error`](#error-types)
* **`error`:** `Unprocessable entity`
* **Retryable:** No
* **What happened:** The page needs a login or a subscription.
* **How to fix:** The page needs a login or a subscription, so there is no content to return. Retrying will not help: fetch another source.
* **More:** [422 Content could not be extracted](#422)

#### `target_rate_limited`

* **Status:** `429`
* **Type:** [`target_error`](#error-types)
* **`error`:** `Rate limit exceeded`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The target site rate-limited the fetch.
* **How to fix:** The target site rate-limited the fetch. This is not your Keenable limit: wait for Retry-After and retry, or fetch another source.
* **More:** [429 Rate limit exceeded](#429)

#### `target_timeout`

* **Status:** `504`
* **Type:** [`target_error`](#error-types)
* **`error`:** `Gateway timeout`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The page took too long to respond.
* **How to fix:** The page took too long to respond. Retrying can help: wait a few seconds and retry up to 3 times, then try another URL.
* **More:** [5xx Server error](#5xx)

#### `target_unreachable`

* **Status:** `502`
* **Type:** [`target_error`](#error-types)
* **`error`:** `Bad gateway`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The fetcher could not reach the page.
* **How to fix:** The fetcher could not reach the page: a connection, DNS or TLS failure, or a server error on the site. This is often transient: wait a few seconds and retry up to 3 times, then try another URL.
* **More:** [5xx Server error](#5xx)

#### `target_wrong_page`

* **Status:** `422`
* **Type:** [`target_error`](#error-types)
* **`error`:** `Unprocessable entity`
* **Retryable:** No
* **What happened:** The site served a different page than the one requested.
* **How to fix:** The site served a different page than the one requested, such as a redirect to its home page. Retrying will not help: check the URL or fetch another source.
* **More:** [422 Content could not be extracted](#422)

### Fallback codes

An error with no more specific code gets one of these, based on its HTTP status. A `400` with no specific code gets [`invalid_request`](#invalid-request). A fallback code keeps the type listed for it whatever the status. Every `402` and `451` the API sends has its own [`billing_error`](#error-types) code, so a fallback never stands for a billing or payment problem.

#### `allowance_unavailable`

* **Status:** `503`
* **Type:** [`api_error`](#error-types)
* **`error`:** `Allowance check unavailable`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** ZeroClick could not confirm the agent's allowance just now.
* **How to fix:** ZeroClick could not confirm the allowance, and nothing was charged. Wait for Retry-After and send the same call again.

#### `auth_internal_error`

* **Status:** `500`
* **Type:** [`api_error`](#error-types)
* **`error`:** `Authentication service error`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The credentials could not be checked because of an error on the Keenable side; they may be fine.
* **How to fix:** Your credentials could not be checked because of an error on our side; they may be fine. Wait for Retry-After and retry up to 3 times. If it keeps failing, report it with the request\_id.

#### `balance_check_unavailable`

* **Status:** `500`
* **Type:** [`api_error`](#error-types)
* **`error`:** `Balance check failed`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The organization's credit balance could not be read, so the request was not run.
* **How to fix:** Your balance could not be read on our side; nothing was charged and your credits are fine. Wait for Retry-After and retry up to 3 times, then report the request\_id.

#### `billing_account_not_found`

* **Status:** `500`
* **Type:** [`api_error`](#error-types)
* **`error`:** `Billing record missing`
* **Retryable:** No
* **What happened:** The organization has no balance record, so the request could not be billed.
* **How to fix:** Your organization has no billing record on our side, so the request could not be billed. Retrying will not help: contact us at [https://keenable.ai/contact](https://keenable.ai/contact) with the request\_id.

#### `card_storage_unavailable`

* **Status:** `503`
* **Type:** [`api_error`](#error-types)
* **`error`:** `Card storage unavailable`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The card could not be read from storage on the Keenable side.
* **How to fix:** The card could not be read from our storage. Wait for Retry-After and retry; if it keeps failing, report it with the request\_id.

#### `card_too_large`

* **Status:** `500`
* **Type:** [`api_error`](#error-types)
* **`error`:** `Card too large`
* **Retryable:** No
* **What happened:** The stored card is larger than the 1 MiB that is served.
* **How to fix:** This card is larger than the 1 MiB we serve, so retrying returns the same error. Report it with the request\_id.

#### `device_login_unavailable`

* **Status:** `503`
* **Type:** [`api_error`](#error-types)
* **`error`:** `Device login unavailable`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The login store did not respond, so the device login could not start or be checked.
* **How to fix:** Wait for Retry-After and retry the same request.

#### `dns_lookup_failed`

* **Status:** `422`
* **Type:** [`api_error`](#error-types)
* **`error`:** `DNS lookup failed`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The domain's DNS records could not be looked up just now.
* **How to fix:** The domain's DNS records could not be looked up just now. Wait for Retry-After and verify again; if it keeps failing, check that the domain's name servers answer.

#### `fetch_mode_unavailable`

* **Status:** `500`
* **Type:** [`api_error`](#error-types)
* **`error`:** `Fetch mode unavailable`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The fetch mode this request needs is turned off on the Keenable side.
* **How to fix:** The fetch mode this request needs is turned off on our side; your URL is not the cause. Wait for Retry-After and retry. If you sent live=true, retrying without it may return the indexed copy.

#### `fetcher_unavailable`

* **Status:** `500`
* **Type:** [`api_error`](#error-types)
* **`error`:** `Fetcher unavailable`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** Keenable's fetcher failed or could not be reached; the URL is not the cause.
* **How to fix:** Our fetcher failed; the URL is not the cause and nothing was charged. Wait for Retry-After and retry the same request up to 3 times, then report the request\_id.

#### `forbidden`

* **Status:** `403`
* **Type:** [`permission_error`](#error-types)
* **`error`:** `Forbidden`
* **Retryable:** No
* **What happened:** The request is not allowed; the message gives the reason.
* **How to fix:** This request is not allowed: read "message" for the reason. Retrying the same request returns the same 403.
* **More:** [403 Key rejected or revoked](#403)

#### `internal_error`

* **Status:** `500`
* **Type:** [`api_error`](#error-types)
* **`error`:** `Internal server error`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** Something failed on the Keenable side, usually with 500; any other 5xx without a more specific code also uses it.
* **How to fix:** Something failed on our side; the request itself may be fine. Wait a few seconds and retry up to 3 times, then report it with the request\_id.
* **More:** [5xx Server error](#5xx)

#### `monitors_unavailable`

* **Status:** `503`
* **Type:** [`api_error`](#error-types)
* **`error`:** `Monitors temporarily unavailable`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The Monitors service did not answer just now.
* **How to fix:** The Monitors service did not answer just now; the request may not have been applied. Wait a few seconds and retry; send an Idempotency-Key with creates so a retry cannot make a second monitor.

#### `not_found`

* **Status:** `404`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Not found`
* **Retryable:** No
* **What happened:** Nothing was found for this request.
* **How to fix:** Nothing was found for this request: read "message", correct it and retry.
* **More:** [404 Page not found](#404)

#### `payment_verification_unavailable`

* **Status:** `502`
* **Type:** [`api_error`](#error-types)
* **`error`:** `Payment verification failed`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The x402 facilitator failed while verifying the payment; nothing was charged.
* **How to fix:** Verification moves no funds, so the same payment is still good. Wait for Retry-After and resend the same request with the same PAYMENT-SIGNATURE.

#### `rate_limited`

* **Status:** `429`
* **Type:** [`rate_limit_error`](#error-types)
* **`error`:** `Rate limit exceeded`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** Too many requests to this endpoint in a short time.
* **How to fix:** Wait for Retry-After and retry, and send requests less often.
* **More:** [429 Rate limit exceeded](#429)

#### `request_rejected`

* **Status:** `409`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Request rejected`
* **Retryable:** No
* **What happened:** The request was rejected, usually with 409 Conflict; any other 4xx without a more specific code also uses it. The message names the step to take first.
* **How to fix:** The request was rejected: read "message" for the step to take first. Retrying the same request unchanged returns the same error.

#### `search_failed_upstream`

* **Status:** `422`
* **Type:** [`api_error`](#error-types)
* **`error`:** `Search failed`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The search backend answered with an unexpected status; the cause was not identified.
* **How to fix:** Search failed with an unexpected status from our backend, and nothing was charged. Wait for Retry-After and retry once; if it fails again, report the request\_id.

#### `search_upstream_error`

* **Status:** `500`
* **Type:** [`api_error`](#error-types)
* **`error`:** `Search backend failed`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The search backend failed while answering; the request itself is not the cause.
* **How to fix:** Our search backend failed; your request is not the cause and nothing was charged. Wait for Retry-After and retry up to 3 times, then report the request\_id.

#### `select_disabled`

* **Status:** `502`
* **Type:** [`api_error`](#error-types)
* **`error`:** `SELECT switched off`
* **Retryable:** No
* **What happened:** Paid SELECT is switched off or not deployed right now; nothing was charged.
* **How to fix:** Paid SELECT is switched off on our side right now, and nothing was charged. Retrying now returns the same error: try again later, or use search and fetch in the meantime.

#### `select_internal_error`

* **Status:** `502`
* **Type:** [`api_error`](#error-types)
* **`error`:** `SELECT failed`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The SELECT service answered in a way Keenable could not use; nothing was charged.
* **How to fix:** This is a fault on our side, not in your query, and nothing was charged. Wait for Retry-After and retry once; if it repeats, report the request\_id.

#### `select_timeout`

* **Status:** `502`
* **Type:** [`api_error`](#error-types)
* **`error`:** `SELECT timed out`
* **Retryable:** No
* **What happened:** The SELECT service did not answer in time, so the result was withheld; nothing was charged.
* **How to fix:** Nothing was charged. A long query is the usual cause, so narrowing it (add LIMIT, filter WEB\_SEARCH, or set show\_preview to true) is the surest fix. If the query is already small, the service was slow: retry once later.

#### `select_unavailable`

* **Status:** `502`
* **Type:** [`api_error`](#error-types)
* **`error`:** `SELECT unavailable`
* **Retryable:** Yes, after `retry_after_seconds`
* **What happened:** The SELECT service failed or could not be reached; nothing was charged.
* **How to fix:** Nothing was charged. Wait for Retry-After and send the same query again, at most 2 more times; then report the request\_id.

#### `service_not_configured`

* **Status:** `503`
* **Type:** [`api_error`](#error-types)
* **`error`:** `Not configured`
* **Retryable:** No
* **What happened:** The feature this endpoint needs is not configured on this server.
* **How to fix:** This endpoint is not configured on our side, so retrying will not help until we fix it. Report it with the request\_id.

#### `unauthenticated`

* **Status:** `401`
* **Type:** [`authentication_error`](#error-types)
* **`error`:** `Authentication required`
* **Retryable:** No
* **What happened:** The request was not authenticated; the message names what is missing or wrong.
* **How to fix:** Read "message" for the credential that is missing or was rejected, sign in again or send a valid key, and retry.

#### `unprocessable`

* **Status:** `422`
* **Type:** [`invalid_request_error`](#error-types)
* **`error`:** `Unprocessable entity`
* **Retryable:** No
* **What happened:** The request was understood but could not be completed.
* **How to fix:** The request was understood but could not be completed: read "message". Retrying the same request returns the same 422.
* **More:** [422 Content could not be extracted](#422)

## 400 Invalid request parameters

**Retry: fix, then retry.**

**What you see**

If a parameter is missing or invalid, search and fetch return `400` with an `error` such as `Invalid parameter`. This fetch call has no `url`:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "error": "Missing required parameter",
  "type": "invalid_request_error",
  "code": "missing_parameter",
  "message": "\"url\" is required",
  "fix": "Send the \"url\" parameter; it is required. Then retry.",
  "docs_url": "https://docs.keenable.ai/errors#missing-parameter",
  "retryable": false,
  "param": "url"
}
```

The `code` is one of the [validation codes](#validation-codes). `param` names the parameter that failed. An `invalid_request` error adds `details`, which lists each failing field. A JSON body that is too large returns `413` with the code `request_too_large`.

A parameter you send either takes effect or the request fails. Search and fetch don't ignore a parameter they don't know, and they don't guess at a value they can't read: `"max_results": true` and `live=1` return `400`. An integer parameter, such as `max_results`, `snippet_max_length` or `max_chars`, accepts its value as a number or as a string of digits, such as `"5"`. The value must still be inside the range the reference lists. An `unknown_parameter` error adds `allowed`, the parameters the endpoint accepts. When the name is close to a supported one, `message` asks `Did you mean`, and `did_you_mean` maps the name you sent to the one to use. This search call sends `count` instead of `max_results`:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "error": "Bad request",
  "type": "invalid_request_error",
  "code": "unknown_parameter",
  "message": "Unknown parameter(s): count. Did you mean max_results? Supported parameters: query, mode, query_time, snippet_max_length, max_results, disable_cards, acquired_after, acquired_before, published_after, published_before, site",
  "fix": "Rename \"count\" to \"max_results\". Then retry.",
  "docs_url": "https://docs.keenable.ai/errors#unknown-parameter",
  "retryable": false,
  "param": "count",
  "allowed": ["query", "mode", "query_time", "snippet_max_length", "max_results", "disable_cards", "acquired_after", "acquired_before", "published_after", "published_before", "site"],
  "did_you_mean": { "count": "max_results" }
}
```

Rename the parameter as `did_you_mean` says and send the call again. A required parameter sent under another name, such as `q` for `query`, returns this error too.

**Cause**

A request parameter does not match what the endpoint accepts: a missing `query` or `url`, a parameter the endpoint doesn't know, a value outside its range, a bad date filter, or a type the schema rejects. A `POST` body that isn't a JSON object sent with `Content-Type: application/json` returns `invalid_request`. Both the keyed paths, such as `/v1/search` and `/v1/fetch`, and the `/public` paths return it. If your organization has a zero data retention policy, a request it doesn't allow returns `400` with the code `zdr_unsupported_profile` or `zdr_prompt_unsupported`.

**Fix**

1. Read the `fix`, `param` and any `details` in the response body. They name the field that failed and what to change.
2. Check the request against the [Search](https://docs.keenable.ai/api-reference/search.md) or [Fetch](https://docs.keenable.ai/api-reference/fetch.md) parameter list and send the call again with a corrected body.
3. If the body says `Missing app identifier` instead, see [400 Missing app identifier](#400-missing-app-identifier).

## 400 Missing app identifier

**Retry: fix, then retry.**

**What you see**

```json theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "error": "Missing app identifier",
  "type": "invalid_request_error",
  "code": "missing_app_title",
  "message": "X-Keenable-Title header is required for token-less requests",
  "fix": "Name your app in the X-Keenable-Title header (or the keenable_title query parameter) and retry. With an API key, call /v1/search or /v1/fetch instead, which do not need it.",
  "docs_url": "https://docs.keenable.ai/errors#missing-app-title",
  "retryable": false,
  "param": "X-Keenable-Title"
}
```

The SDKs send this header for you, so you get this error only over raw HTTP.

**Cause**

A keyless request to `/v1/search/public` or `/v1/fetch/public` arrived without the `X-Keenable-Title` header. Keyed requests to `/v1/search` or `/v1/fetch` never need this header. A `400` on those paths means an [invalid parameter](#400-invalid-request).

**Fix**

Add the header with your application's name. If you can't set a header, pass the same value in the `keenable_title` query parameter. This request includes the header:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
curl -X POST https://api.keenable.ai/v1/search/public \
  -H "Content-Type: application/json" \
  -H "X-Keenable-Title: My agent" \
  -d '{"query": "fastest inference providers 2026", "max_results": 3}'
```

You get search results instead of the `400`. If you have an [API key](https://docs.keenable.ai/api-keys.md), call `/v1/search` instead, which doesn't need the header.

## 401 Missing key

**Retry: fix, then retry.**

**What you see**

If a request to a keyed path such as `/v1/search` or `/v1/fetch` carries no key at all, the API returns:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "error": "Missing authentication",
  "type": "authentication_error",
  "code": "missing_api_key",
  "message": "Either X-API-Key header or Authorization Bearer token is required",
  "fix": "Send your Keenable API key in the X-API-Key header (or as \"Authorization: Bearer <key>\") and retry. Create a key at https://app.keenable.ai/console/api-keys.",
  "keyless": "/v1/search/public and /v1/fetch/public work without a key, rate-limited per IP. Name your app in the X-Keenable-Title header (or the keenable_title query parameter); public requests without it get a 400.",
  "api_keys_url": "https://app.keenable.ai/console/api-keys",
  "docs_url": "https://docs.keenable.ai/errors#missing-api-key",
  "retryable": false
}
```

The `keyless` field appears only on `/v1/search` and `/v1/fetch`, which have a `/public` twin. A `401` from the time machine endpoints leaves it out.

The SDKs never send a request with no key. If `KEENABLE_API_KEY` isn't set, they call the keyless `/public` paths, so you get this body only over raw HTTP.

**Cause**

The request reached a keyed path without an `X-API-Key` or `Authorization: Bearer` header.

**Fix**

Send the key in the `X-API-Key` header. To call without a key, use `/v1/search/public` or `/v1/fetch/public` with an `X-Keenable-Title` header instead.

## 401 Malformed key

**Retry: fix, then retry.**

**What you see**

If the key has the wrong format, the API returns `401` with `"error": "Authentication failed"`, `"message": "Malformed API key"` and the code `invalid_api_key`. That code also covers an [unknown key](#401-invalid-key), so check the `message`. A request with no key at all gets [`missing_api_key`](#401-missing-key) instead.

The SDKs raise `KeenableAuthError` (Python, TypeScript), `*keenable.AuthError` (Go) or `keenable::Error::Auth` (Rust) with the message prefix `Keenable authentication failed (401)`.

**Cause**

`Malformed API key` means the value does not look like a Keenable key at all. Common causes are a truncated copy, a stray quote or space, or a placeholder such as `keen_<your_key>` left in place.

**Fix**

1. Check the value of `KEENABLE_API_KEY`. It starts with `keen_` and has no quotes or whitespace around it.
2. Over raw HTTP, send the key in the `X-API-Key` header. To call without a key, use `/v1/search/public` or `/v1/fetch/public` with an `X-Keenable-Title` header instead.
3. To keep working while you sort it out, unset `KEENABLE_API_KEY`. The SDKs fall back to the keyless tier.

## 401 Invalid key

**Retry: fix, then retry.**

**What you see**

The API returns:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "error": "Authentication failed",
  "type": "authentication_error",
  "code": "invalid_api_key",
  "message": "Invalid API key",
  "fix": "The API key was not accepted. Copy the full key from https://app.keenable.ai/console/api-keys, or create a new one there, and retry with it in the X-API-Key header.",
  "keyless": "/v1/search/public and /v1/fetch/public work without a key, rate-limited per IP. Name your app in the X-Keenable-Title header (or the keenable_title query parameter); public requests without it get a 400.",
  "api_keys_url": "https://app.keenable.ai/console/api-keys",
  "docs_url": "https://docs.keenable.ai/errors#invalid-api-key",
  "retryable": false
}
```

The SDKs raise `KeenableAuthError` (Python, TypeScript), `*keenable.AuthError` (Go) or `keenable::Error::Auth` (Rust) with the message prefix `Keenable authentication failed (401)`.

**Cause**

The key has the right format, but Keenable has no key with that value. A typo that keeps the `keen_` prefix causes this. A [malformed key](#401-malformed-key) returns the same `invalid_api_key` code with `"message": "Malformed API key"`, so check the `message` to tell the two apart. If you sent a bearer token that isn't an API key and it was rejected, see [401 Invalid token](#401-invalid-token).

**Fix**

1. Compare `KEENABLE_API_KEY` with the key in the [console ↗](https://app.keenable.ai/console).
2. If you cannot find it there, create a new key and replace the old value. See [API keys](https://docs.keenable.ai/api-keys.md).
3. To keep working while you sort it out, unset `KEENABLE_API_KEY`. The SDKs fall back to the keyless tier.

## 401 Invalid token

**Retry: fix, then retry.**

**What you see**

The API returns `401` with `"error": "Authentication failed"` and the code `invalid_bearer_token`.

**Cause**

The request sent a bearer token in `Authorization: Bearer` that isn't an API key, and the token was malformed or expired. A bearer value that looks like a Keenable API key is checked as a key, so a bad key there gets [`invalid_api_key`](#401-invalid-key) instead.

**Fix**

Sign in again for a fresh token, or send an [API key](https://docs.keenable.ai/api-keys.md) in the `X-API-Key` header.

## 402 Out of funds

**Retry: do not retry.**

**What you see**

Over HTTP, the body has the code `insufficient_credits` and `"retryable": false`. It adds `billing_url`, where to top up, and `auto_top_up_url`, which links [auto top-up](https://docs.keenable.ai/auto-top-up.md). Where pay-per-request is enabled, `pay_per_request` describes the [x402](https://docs.keenable.ai/pay-per-request.md) paths, which an agent with a crypto wallet can call with no key or credits.

The SDKs raise `KeenableInsufficientCreditsError` (Python, TypeScript), a subclass of `KeenableAPIError`, `*keenable.InsufficientCreditsError` (Go) or `keenable::Error::InsufficientCredits` (Rust) with status `402` and the message prefix `Keenable: insufficient credits (402)`.

**Cause**

Your organization has spent its free monthly allowance, 100,000 requests on the standard plan, and its prepaid balance is used up. Every retry returns the same `402` until someone tops up or the allowance resets. See [Balance and usage](https://docs.keenable.ai/credits.md#when-credits-run-out).

**Fix**

Stop and ask a human to top up or turn on [auto top-up](https://docs.keenable.ai/auto-top-up.md) in the [console ↗](https://app.keenable.ai/console).

Catch the API error and check its status. The dedicated credits error is a subclass of it, so this works in every SDK version. This code stops on `402` and passes every other error through:

```typescript TypeScript theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
import { Keenable, KeenableAPIError } from "keenable";

const client = new Keenable();
try {
  const results = await client.search("fastest inference providers 2026", { maxResults: 3 });
} catch (err) {
  if (err instanceof KeenableAPIError && err.statusCode === 402) {
    // Out of funds: retrying will not help. Hand off to a human.
    throw new Error("Keenable is out of funds. Top up or turn on auto top-up in the console.");
  }
  throw err;
}
```

```python Python theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
from keenable import Keenable, KeenableAPIError

client = Keenable()
try:
    results = client.search("fastest inference providers 2026", max_results=3)
except KeenableAPIError as err:
    if err.status_code == 402:
        # Out of funds: retrying will not help. Hand off to a human.
        raise SystemExit("Keenable is out of funds. Top up or turn on auto top-up in the console.")
    raise
```

```go Go theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
_, err := client.Search(ctx, "fastest inference providers 2026",
	&keenable.SearchOptions{MaxResults: 3})
var apiErr *keenable.APIError
if errors.As(err, &apiErr) && apiErr.StatusCode == 402 {
	// Out of funds: retrying will not help. Hand off to a human.
	log.Fatal("Keenable is out of funds. Top up or turn on auto top-up in the console.")
}
if err != nil {
	log.Fatal(err)
}
```

Your program exits with the message instead of retrying. The SDKs also have a typed error for `402`: `KeenableCreditsError` in Python and TypeScript, `*keenable.CreditsError` in Go. You can catch that type instead of checking the status.

## 403 Key rejected or revoked

**Retry: do not retry; check the key, then ask a human.**

**What you see**

A revoked key returns:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "error": "Forbidden",
  "type": "permission_error",
  "code": "credentials_forbidden",
  "message": "Key revoked",
  "fix": "The credentials were recognized but are not allowed, usually because the key was revoked. Retrying with them will not help: create a new key at https://app.keenable.ai/console/api-keys, or ask a human with console access to create one for you.",
  "api_keys_url": "https://app.keenable.ai/console/api-keys",
  "docs_url": "https://docs.keenable.ai/errors#credentials-forbidden",
  "retryable": false
}
```

On `/v1/search` and `/v1/fetch`, the body also has `keyless`, the same `/public` alternative a `401` names.

The SDKs raise `KeenableAuthError` (Python, TypeScript), `*keenable.AuthError` (Go) or `keenable::Error::Auth` (Rust) with the message prefix `Keenable authentication failed (403)`.

**Cause**

`403` means the server won't accept this key. Two cases return the same status:

* On `/v1/search`, `/v1/fetch` and `/mcp`, the key usually exists but was [revoked](https://docs.keenable.ai/api-keys.md#key-lifetime-and-rotation) in your organization.
* On `/mcp-public`, a key the server doesn't accept also returns `403`, not `401`, so a mistyped or unknown key looks like a revoked one. See [MCP server](https://docs.keenable.ai/mcp-server.md#keyless-endpoint-for-listings-and-presets).

Fetch also returns `403` for reasons unrelated to your key. Check the `code` before you touch the key:

* `target_blocked` (`"error": "Upstream forbidden"`): the target site blocked the fetch, for example with a bot check. Try a different URL.
* `private_url_not_allowed`: the URL points at a private or internal address. Use a public `http` or `https` URL.
* `forbidden`: the request isn't allowed for another reason, such as a search mode your access doesn't include. `message` says which.

**Fix**

1. Compare the key value with the one in the [console ↗](https://app.keenable.ai/console). Fix typos, stray quotes and leftover placeholders before treating the key as revoked.
2. If the value matches and still gets `403`, ask a human with console access to issue a new key, then update `KEENABLE_API_KEY`.
3. On `/mcp-public`, you can also drop the key and stay on the public tier, or switch the URL to `/mcp` once the key is confirmed.

## 403 Time Machine not enabled

**Retry: do not retry; remove `query_time` or ask a human.**

**What you see**

A Time Machine search or fetch from an organization without the feature returns `403` with `"error": "Feature not enabled"`, `"feature": "time_machine"` and a `message` that names both ways forward.

**Cause**

Time Machine, which searches and fetches the web as of a past date, isn't enabled for your organization.

**Fix**

Remove the `query_time` parameter and call `/v1/search` or `/v1/fetch`, which return current results. To keep the past date, ask a human to enable Time Machine for the organization.

## 404 Page not found

**Retry: fix the URL, then retry.**

**What you see**

If the target page doesn't exist, fetch returns `404`:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "error": "Not found",
  "type": "target_error",
  "code": "page_not_found",
  "message": "The page does not exist at this URL. Check that the URL is correct.",
  "fix": "The site says the page does not exist. Retrying the same URL returns the same 404: check the URL, or use another search result.",
  "docs_url": "https://docs.keenable.ai/errors#page-not-found",
  "retryable": false
}
```

Search returns `404` only when `query` is a URL, which it fetches instead of searching.

**Cause**

Keenable couldn't find the URL you passed to [Fetch](https://docs.keenable.ai/api-reference/fetch.md): a typo, a moved page, or a link that never resolved.

**Fix**

Check the URL, then call fetch again with a corrected one. Retrying the same URL returns the same `404`. If search gave you the link, try the next result instead.

## 405 Wrong HTTP method

**Retry: fix the method, then retry.**

**What you see**

The path exists but doesn't take the method you used, for example a `POST` to fetch:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "error": "Method not allowed",
  "type": "invalid_request_error",
  "code": "method_not_allowed",
  "message": "/v1/fetch/public does not accept POST. Use GET. See https://docs.keenable.ai/api-reference",
  "fix": "/v1/fetch/public does not accept POST. Send the request again as GET.",
  "allowed": ["GET"],
  "docs_url": "https://docs.keenable.ai/errors#method-not-allowed",
  "retryable": false
}
```

`allowed` and the `Allow` response header list the methods the path takes.

**Cause**

Search takes `GET` or `POST`. Fetch takes only `GET`, with the page in the `url` query parameter.

**Fix**

Send the request again with a method from `allowed`. For fetch, that's `GET /v1/fetch?url=...`. The [SDKs](https://docs.keenable.ai/sdks.md) pick the right method for you.

## 422 Content could not be extracted

**Retry: fix the URL or skip; do not retry the same URL.**

**What you see**

If the page exists but Keenable can't extract readable content from it, fetch returns `422` with `"error": "Unprocessable entity"`, `"retryable": false` and a `message` such as `The page is behind a login or paywall`. The `code` says why:

| Code | Meaning |
| - | - |
| `target_paywalled` | The page needs a login or a subscription. |
| `target_blocked` | The site served a bot check instead of the page. |
| `target_wrong_page` | The site served a different page, such as a redirect to its home page. |
| `content_not_extracted` | The page was reached but has no readable text. |
| `target_http_error` | The site answered with an error status for this URL. |

Search returns `422` with `Search failed` and a status code in the `message` when Keenable's search backend answers with an unexpected status. That one is retryable: wait for `Retry-After`, retry once, then [report it](#report-a-problem).

**Cause**

The URL is reachable, but extraction failed: an unsupported domain, a login wall or paywall, a page that is mostly binary or empty of text, an error status from the target site, or a failure inside the extractor.

**Fix**

Don't retry the same URL. It fails the same way every time. Try a different URL from search, or fetch a cleaner source for the same topic. If many URLs from one site fail, the domain is probably unsupported, so skip that site.

## 429 Rate limit exceeded

**Retry: wait, then retry.**

**What you see**

Over HTTP, the `code` says which limit you hit, and `retry_after_seconds` says how long to wait. A `429` from one of Keenable's own limits adds `limit`, with its `scope`, `window`, `max` and `resets_at`. See [Error body](#error-body) for an example.

The SDKs raise `KeenableRateLimitError` (Python, TypeScript), `*keenable.RateLimitError` (Go) or `keenable::Error::RateLimit` (Rust) with the message prefix `Keenable rate limit exceeded (429)`.

Keyless responses carry these headers for the hourly window, and every `429` adds `Retry-After`. Keyed responses carry only `Retry-After`, on a `429`, so pace keyed calls with it.

| Header | Meaning |
| - | - |
| `X-RateLimit-Limit` | Keyless requests allowed per hour |
| `X-RateLimit-Remaining` | Keyless requests left in the current hour |
| `X-RateLimit-Reset` | When the hourly window resets, as an ISO 8601 timestamp |
| `Retry-After` | How long to wait before the next request |

**Cause**

You sent requests faster than your limit allows:

* `public_rate_limit_hourly` and `public_rate_limit_per_second`: keyless, 1,000 requests per hour and 10 per second per IP, on a pool shared with everyone else on your egress address.
* `rate_limit_per_second`: with an API key, 10 requests per second per organization by default, with no hourly cap.
* `paid_rate_limit_per_second`: [pay per request](https://docs.keenable.ai/pay-per-request.md#limits), per paying wallet, per IP, or per agent for ZeroClick.

See [rate limits](https://docs.keenable.ai/rate-limits.md) for every tier.

A `429` can also come from further down the line. The codes `target_rate_limited` (the target server rate-limited the fetch), `search_rate_limited` and `fetch_rate_limited` mean your own limit isn't the cause. Those responses carry `Retry-After: 1`.

**Fix**

Wait for the time in `Retry-After`, then retry. If you hit the keyless hourly cap, retrying before `limit.resets_at` returns `429` again. Add an [API key](https://docs.keenable.ai/api-keys.md) instead: it removes the hourly cap and gives you your own limit. For a higher per-second limit, see [Raise your limit](https://docs.keenable.ai/rate-limits.md#raise-your-limit).

## 5xx Server error

**Retry: retry up to 3 times.**

**What you see**

Over HTTP, the body has `"retryable": true` and `retry_after_seconds`, and the response has a matching `Retry-After` header.

The SDKs raise `KeenableAPIError` (Python, TypeScript), `*keenable.APIError` (Go) or `keenable::Error::Api` (Rust) with the message prefix `Keenable API error (5xx)`, where `5xx` is the actual status, such as `500` or `503`.

**Cause**

Something failed on Keenable's side or on the way to the target page. The request itself is fine. The `code` tells the cases apart:

* `500` `internal_error`: something failed on Keenable's side. The response carries `Retry-After: 2`.
* `500` `search_upstream_error`: Keenable's search backend failed while answering. Nothing was charged. The response carries `Retry-After: 2`.
* `500` `fetcher_unavailable`: Keenable's fetcher failed. The URL isn't the cause. The response carries `Retry-After: 5`.
* `500` `fetch_mode_unavailable`: this fetch mode is turned off for a while on Keenable's side. The response carries `Retry-After: 30`.
* `502` `target_unreachable`: fetch couldn't reach the target page, for example after a DNS, TLS or connection failure. The response carries `Retry-After: 2`.
* `503` `auth_unavailable`: Keenable couldn't verify your key. The response carries `Retry-After: 5`.
* `504` `target_timeout`: the target page took too long to respond. The response carries `Retry-After: 5`.
* `529` `search_overloaded`: search is temporarily overloaded. The response carries `Retry-After: 1`.

The pay-per-request paths have their own `502` and `503` codes, listed under [credits and payment codes](#credits-and-payment-codes).

**Fix**

Retry up to 3 times, waiting longer before each attempt (for example 1, 2 and 4 seconds). If the response has a `Retry-After` header, wait at least that long. If the error persists after 3 attempts, stop and [report it](#report-a-problem).

## Report a problem

Responses carry an `X-Request-Id` header, and error bodies repeat it as `request_id`. Include its value when you [get help](https://docs.keenable.ai/help.md), so we can find your request in our logs. The Go and Rust SDKs add it to the error message as `request_id`.

If a response has no request ID, include the time of the request and the full response body.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.