Skip to main content
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. 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, Python, Go and Rust.

Troubleshooting

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

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:
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: 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.

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 show the usual value for each code. 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. A pay-per-request 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. 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. Some waits are long: after public_rate_limit_hourly, Retry-After can be up to an hour. The SDKs 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, 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, 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.

authentication_error

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

permission_error

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

billing_error

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

rate_limit_error

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

target_error

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

api_error

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

Authentication codes

Missing, malformed, unknown or revoked credentials.

admin_required

  • Status: 403
  • Type: permission_error
  • 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: 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.

auth_unavailable

  • Status: 503
  • Type: api_error
  • 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

company_email_required

  • Status: 403
  • Type: permission_error
  • 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: 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, or ask a human with console access to create one for you.
  • More: 403 Key rejected or revoked

device_code_denied

  • Status: 400
  • Type: permission_error
  • 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

invalid_authorization_header

  • Status: 401
  • Type: authentication_error
  • 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), and retry.

invalid_bearer_token

invalid_session_token

  • Status: 401
  • Type: authentication_error
  • 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 for a fresh token and retry. API keys do not work on console endpoints.

mcp_host_not_allowed

  • Status: 403
  • Type: permission_error
  • 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) so the Host header matches, and retry.

mcp_origin_not_allowed

  • Status: 403
  • Type: permission_error
  • 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: 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

missing_session_token

  • Status: 401
  • Type: authentication_error
  • 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 for a token.

mode_requires_api_key

  • Status: 403
  • Type: permission_error
  • 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) on /v1/search, or drop “mode” (or set it to “pro” or “realtime”) and retry.

monitor_limit_reached

  • Status: 403
  • Type: permission_error
  • 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: 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 to turn it on. Retrying returns the same 403.

promo_card_required

  • Status: 403
  • Type: permission_error
  • 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: 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: 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: 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: 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), and retry. Keyless MCP works on the default endpoint without WebQL mode.

time_machine_not_enabled

  • Status: 403
  • Type: permission_error
  • 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 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: 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: 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: 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: 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: 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) on /v1/search and /v1/fetch.

zeroclick_signing_key_unknown

  • Status: 401
  • Type: authentication_error
  • 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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

invalid_request

  • Status: 400
  • Type: invalid_request_error
  • 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

last_admin

  • Status: 409
  • Type: invalid_request_error
  • 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: 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: 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: 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: 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

missing_parameter

  • Status: 400
  • Type: invalid_request_error
  • 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

monitor_option_not_supported

  • Status: 400
  • Type: invalid_request_error
  • 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: 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, or call with an API key, then retry.

query_rejected

  • Status: 400
  • Type: invalid_request_error
  • 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: 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: 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

route_not_found

  • Status: 404
  • Type: invalid_request_error
  • 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 (for example /v1/search or /v1/fetch) and retry.

search_rejected_upstream

  • Status: 400
  • Type: invalid_request_error
  • 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: 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, then send it again.

select_query_invalid

  • Status: 400
  • Type: invalid_request_error
  • 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, then send it again. Retrying it unchanged returns the same 400.

unknown_parameter

  • Status: 400
  • Type: invalid_request_error
  • 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

unknown_tool

  • Status: 400
  • Type: invalid_request_error
  • 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: 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: 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: 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: 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: 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: 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

zdr_unsupported_profile

  • Status: 400
  • Type: invalid_request_error
  • 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

Credits and payment codes

Credits for keyed requests, and payments on the pay-per-request paths.

insufficient_credits

  • Status: 402
  • Type: billing_error
  • 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).
  • More: 402 Out of credits

payment_facilitator_error

  • Status: 502
  • Type: api_error
  • 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

payment_rejected

  • Status: 402
  • Type: billing_error
  • 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: 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

payment_settlement_failed

  • Status: 402
  • Type: billing_error
  • 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

payments_region_unavailable

  • Status: 451
  • Type: billing_error
  • 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) instead.
  • More: Pay per request errors

payments_unavailable

  • Status: 503
  • Type: api_error
  • 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).
  • More: Pay per request errors

zeroclick_allowance_denied

  • Status: 402
  • Type: billing_error
  • 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) on /v1/search and /v1/fetch.

Rate limit codes

Your own limits, and Keenable services that are briefly busy. See Rate limits for every tier.

fetch_rate_limited

  • Status: 429
  • Type: rate_limit_error
  • 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
  • Status: 429
  • Type: rate_limit_error
  • 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) on /v1/search and /v1/fetch.
  • More: 429 Rate limit exceeded

public_domain_requires_api_key

  • Status: 429
  • Type: rate_limit_error
  • 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 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: the free API key includes 100,000 requests a month.

public_rate_limit_domain

  • Status: 429
  • Type: rate_limit_error
  • 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) 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: the free API key includes 100,000 requests a month.

public_rate_limit_hourly

  • Status: 429
  • Type: rate_limit_error
  • 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 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: the free API key includes 100,000 requests a month.
  • More: 429 Rate limit exceeded

public_rate_limit_per_second

rate_limit_per_second

search_overloaded

  • Status: 529
  • Type: api_error
  • 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

search_rate_limited

  • Status: 429
  • Type: rate_limit_error
  • 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

select_concurrency_limited

  • Status: 429
  • Type: rate_limit_error
  • 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: 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: 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

page_not_found

  • Status: 404
  • Type: target_error
  • 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

private_url_not_allowed

  • Status: 403
  • Type: permission_error
  • 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

target_blocked

  • Status: 403
  • Type: target_error
  • 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

target_http_error

  • Status: 422
  • Type: target_error
  • 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

target_paywalled

  • Status: 422
  • Type: target_error
  • 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

target_rate_limited

  • Status: 429
  • Type: target_error
  • 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

target_timeout

  • Status: 504
  • Type: target_error
  • 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

target_unreachable

  • Status: 502
  • Type: target_error
  • 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

target_wrong_page

  • Status: 422
  • Type: target_error
  • 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

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. A fallback code keeps the type listed for it whatever the status. Every 402 and 451 the API sends has its own billing_error code, so a fallback never stands for a billing or payment problem.

allowance_unavailable

  • Status: 503
  • Type: api_error
  • 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: 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: 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: 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 with the request_id.

card_storage_unavailable

  • Status: 503
  • Type: api_error
  • 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: 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: 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: 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: 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: 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: 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

internal_error

  • Status: 500
  • Type: api_error
  • 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

monitors_unavailable

  • Status: 503
  • Type: api_error
  • 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: 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

payment_verification_unavailable

  • Status: 502
  • Type: api_error
  • 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: 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

request_rejected

  • Status: 409
  • Type: invalid_request_error
  • 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: 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: 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: 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: 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: 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: 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: 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: 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: 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

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:
The code is one of the 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:
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 or Fetch 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

Retry: fix, then retry. What you see
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. 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:
You get search results instead of the 400. If you have an API key, 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:
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, so check the message. A request with no key at all gets missing_api_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:
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 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. Fix
  1. Compare KEENABLE_API_KEY with the key in the console ↗.
  2. If you cannot find it there, create a new key and replace the old value. See API keys.
  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 instead. Fix Sign in again for a fresh token, or send an API key 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. Where pay-per-request is enabled, pay_per_request describes the x402 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. Fix Stop and ask a human to top up or turn on auto top-up in the 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:
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:
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 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.
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 ↗. 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:
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: 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:
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 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: 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. 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 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. 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, per paying wallet, per IP, or per agent for ZeroClick.
See rate limits 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 instead: it removes the hourly cap and gives you your own limit. For a higher per-second limit, see 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. 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

Responses carry an X-Request-Id header, and error bodies repeat it as request_id. Include its value when you get help, 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.