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:
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’sretryable 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 usualerror. 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
- Status:
401 - Type:
authentication_error 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, or create a new one there, and retry with it in the X-API-Key header.
- More: 401 Invalid 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
- Status:
401 - Type:
authentication_error 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 in the X-API-Key header.
- More: 401 Invalid 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
- Status:
401 - Type:
authentication_error 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.
- More: 401 Missing 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 asfix says; sending it again unchanged returns the same error.
authorization_pending
- Status:
400 - Type:
invalid_request_error error:authorization_pending- Retryable: Poll again after
intervalseconds. The body has noretryablefield. - 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 loginagain 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 loginagain 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
paid_rate_limit_per_second
- 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
- 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 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) to /v1/search or /v1/fetch for your organization’s own limit. 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
rate_limit_per_second
- Status:
429 - Type:
rate_limit_error 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.
- More: 429 Rate limit exceeded
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
intervalseconds. The body has noretryablefield. - 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 whenquery 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. A400 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 return400 with an error such as Invalid parameter. This fetch call has no url:
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:
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
- Read the
fix,paramand anydetailsin the response body. They name the field that failed and what to change. - Check the request against the Search or Fetch parameter list and send the call again with a corrected body.
- If the body says
Missing app identifierinstead, see 400 Missing app identifier.
400 Missing app identifier
Retry: fix, then retry. What you see/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:
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:
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 returns401 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
- Check the value of
KEENABLE_API_KEY. It starts withkeen_and has no quotes or whitespace around it. - Over raw HTTP, send the key in the
X-API-Keyheader. To call without a key, use/v1/search/publicor/v1/fetch/publicwith anX-Keenable-Titleheader instead. - 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: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
- Compare
KEENABLE_API_KEYwith the key in the console ↗. - If you cannot find it there, create a new key and replace the old value. See API keys.
- 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 returns401 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 codeinsufficient_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:
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:/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/fetchand/mcp, the key usually exists but was revoked in your organization. - On
/mcp-public, a key the server doesn’t accept also returns403, not401, so a mistyped or unknown key looks like a revoked one. See MCP server.
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 publichttporhttpsURL.forbidden: the request isn’t allowed for another reason, such as a search mode your access doesn’t include.messagesays which.
- Compare the key value with the one in the console ↗. Fix typos, stray quotes and leftover placeholders before treating the key as revoked.
- If the value matches and still gets
403, ask a human with console access to issue a new key, then updateKEENABLE_API_KEY. - On
/mcp-public, you can also drop the key and stay on the public tier, or switch the URL to/mcponce the key is confirmed.
403 Time Machine not enabled
Retry: do not retry; removequery_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 returns404:
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 aPOST 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 returns422 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, thecode 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_hourlyandpublic_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.
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:
500internal_error: something failed on Keenable’s side. The response carriesRetry-After: 2.500search_upstream_error: Keenable’s search backend failed while answering. Nothing was charged. The response carriesRetry-After: 2.500fetcher_unavailable: Keenable’s fetcher failed. The URL isn’t the cause. The response carriesRetry-After: 5.500fetch_mode_unavailable: this fetch mode is turned off for a while on Keenable’s side. The response carriesRetry-After: 30.502target_unreachable: fetch couldn’t reach the target page, for example after a DNS, TLS or connection failure. The response carriesRetry-After: 2.503auth_unavailable: Keenable couldn’t verify your key. The response carriesRetry-After: 5.504target_timeout: the target page took too long to respond. The response carriesRetry-After: 5.529search_overloaded: search is temporarily overloaded. The response carriesRetry-After: 1.
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 anX-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.