Skip to main content

Knowledge Base Error Codes

Knowledge endpoints — and chat requests with knowledge_base_ids — use the platform's error envelope with four extra fields:

{
"error": {
"message": "The API key is not permitted to access this knowledge base.",
"type": "authentication_error",
"param": null,
"code": "kb_not_in_allowlist",
"request_id": "8b1f0c6e-…",
"retryable": false,
"retry_after_seconds": null,
"details": { "knowledge_base_id": "3f6c2b1e-8d4a-4c1f-9e2b-7a5d6c3b2a10" }
}
}
FieldRule
codeStable reason code from the tables below. Branch on code only. Codes are never renamed; new ones may be added — treat an unknown code by its HTTP status.
typeDerived from the status (400/404/409/410/413/422 → invalid_request_error, 401/403 → authentication_error, 402 → insufficient_quota, 429 → rate_limit_error, 503 → service_unavailable, 500 → server_error).
messageEnglish, for display. It never contains your content (file names, metadata values, query or chunk text).
paramThe offending field when there is one (metadata.department, filter.must[0].key, files[3]), otherwise null.
request_idCorrelation id; quote it when contacting support.
retryabletrue only when the same request can succeed later without changes.
retry_after_secondsSet on 429, 503 and retryable 409s; mirrored in the Retry-After header.
detailsCode-specific ids, limits and counters (below). Never content, never another organization's data.

A resource that does not exist and a resource that belongs to another organization produce identical 404 not_found bodies — existence never leaks.

Access and existence​

CodeHTTPRetryWhen / details
scope_missing403noThe API key lacks knowledge:read / knowledge:write (or inference:chat for chat). details.required_scope.
kb_not_in_allowlist403noThe key's knowledge-base access list excludes a requested knowledge base, or is empty ([]). A multi-knowledge-base request is refused as a whole. details.knowledge_base_id.
role_insufficient403noA portal member without the admin or owner role attempted a change. details.required_role.
actor_not_permitted403noThis kind of caller cannot use the route.
tenant_suspended403noYour organization is suspended.
not_found404noAbsent, or owned by another organization. details.resource ∈ knowledge_base, document, export, source, source_run, source_preview (an expired preview is not_found too), or tenant on routes that do not start from a knowledge base after your organization's data was deleted.
module_disabled404 / 403noKnowledge bases are switched off on the platform. 404 when your organization has no knowledge bases (every knowledge route, and chat with knowledge_base_ids). 403 when it still has some: existing data stays readable and exportable (starting a new export is allowed) and stays billed, and only operations that create data or start processing are refused — creating a knowledge base, upload, file replacement, retry. GET /v1/knowledge_module then returns "enabled": false, "read_only": true.
export_expired410noThe export link or export is older than its expires_at (24 h), or a document of the knowledge base was deleted or replaced after the export started; the zip is removed by the export cleanup. Start a new export.

Commercial (402)​

Every 402 carries details.price_card_url and details.meter (knowledge_bases, storage_bytes, queries, processing_tokens), plus limit, used and resets_at when known. See Pricing and Billing.

CodeRetryWhen / details
trial_exhaustednoA free-trial allowance is used up and your organization cannot pay as it goes (prepaid with no positive balance). After the trial every organization pays as it goes — from the wallet (prepaid) or on the invoice (postpaid); no plan or commitment covers knowledge bases.
insufficient_creditsnoThe prepaid wallet cannot hold the amount.
credit_limit_exceedednoThe postpaid credit limit would be exceeded.
payg_spend_cap_exceedednoThe organization spending cap is reached; knowledge-base spend counts toward it. Reaching it also blocks ordinary LLM requests — see Spend cap. There is no separate knowledge-base cap.
payment_suspendednoPaid work stopped because of a payment problem. details.suspended_at, details.deletion_at. Download and delete stay open.

State conflicts (409)​

CodeRetryWhen / details
idempotency_key_conflictnoThe same Idempotency-Key was used within 24 h with a different request.
idempotency_in_progressyesThe original request with this key is still running. Retry the same request with the same key after Retry-After (≈2 s).
version_conflictnoA file replacement is already running for this document.
duplicate_contentnoThe same content is already in this knowledge base and on_duplicate=reject. details.existing_document_id.
kb_suspendednoThe knowledge base is suspended because of a payment problem (details.reason: payment_suspended). Search and upload closed; list, download, export, delete open.
kb_deletingnoThe knowledge base is being deleted.
document_deletingnoThe document is being deleted.
document_not_readyno/content or /chunks on a document without a ready version.
invalid_document_statenoretry or cancel in a status that does not allow it (details.status), or a file replacement of a website page (details.origin = "web": new versions come from the site).
trial_kb_frozennoIdle free-trial knowledge base. details.frozen_at, details.deletion_at.
resource_limit_reachednoKnowledge bases per organization, uploaded documents per knowledge base (website pages count against their source's page cap instead), or website sources per knowledge base (limit_name: max_sources_per_kb). details.limit_name, details.limit, details.source (always platform: the limits are the same for every organization).
export_in_progressyesAn export for this knowledge base is already running. details.export_id.

Size (413)​

CodeWhen / details
file_too_largeA file exceeds 50 MB (details.max_bytes). Per file in multi-file uploads; for the whole request on a file replacement.
too_many_filesMore than 50 files in one upload request.
request_too_largeUpload body above 500 MB, or a JSON body above 1 MB.

Validation (422)​

CodeWhereWhen
validation_failedrequestSchema validation (types, required fields, ranges). details.fields[] = {loc, type}; values are never echoed. On POST /v1/knowledge_bases with param: embedding_model: no details.reason = the id is unknown or the model is not offered for knowledge bases; model_unknown = the model was removed from the platform; unpriced = the model has no processing price for your organization right now (details.unpriced_reason). Choose another model from GET /v1/knowledge_embedding_models. On PATCH /v1/knowledge_bases/{kb_id}, any embedding_model is refused with details.reason: immutable: the model cannot be changed — create a new knowledge base instead.
invalid_identifierrequestA path or body id is not a UUID.
metadata_key_reservedrequestMetadata key collides with a platform field.
metadata_too_many_keysrequestMore than 16 metadata keys after the change.
metadata_invalid_keyrequestKey does not match ^[a-z][a-z0-9_]{0,63}$.
metadata_invalid_valuerequestNot a string ≤256 characters, finite number, boolean or date; or null/array/object.
filter_invalidrequestMalformed filter — see Filters.
too_many_knowledge_basesrequestMore than 5 knowledge bases in one chat request.
query_too_longrequestSearch query longer than 2,000 characters.
retrieval_query_missingrequestChat with knowledge_base_ids whose last message is not a user message with text.
tools_not_supported_with_knowledgerequestChat combines knowledge_base_ids with tools or functions.
batch_too_largerequestMore than 100 ids in a batch operation.
unsupported_file_typeupload, documentNot PDF, DOCX, PPTX, XLSX, CSV, HTML, TXT or MD.
file_type_mismatchupload, documentExtension, MIME type and file signature disagree.
corrupt_fileupload, documentStructurally unreadable.
encrypted_fileupload, documentPassword-protected or encrypted.
macro_fileupload, documentOffice file containing macros.
archive_bombupload, documentDOCX/PPTX/XLSX expands beyond the size or entry ceiling.
no_text_contentdocumentNo extractable text (scanned PDF; no OCR).
extraction_limit_exceededdocumentExtracted text, cells, rows or chunks above the ceilings — including more than limits.max_rows_per_document (default 50,000) data rows in an XLSX/CSV file. The document fails instead of being half-indexed.
processing_limit_exceededdocumentProcessing took longer than 1 hour, or the document has more embedding tokens than limits.max_tokens_per_document (default 3,000,000).

"upload" means the file is rejected in the upload response; "document" means the document ends failed with this failure.code after it was accepted.

Website sources​

Codes of website sources. The reasons a source is blocked, a run ended early or a page was skipped (status_reason, stop_reason, skip_reason) are not error codes; they are listed in the website sources guide.

CodeHTTPRetryWhen / details
web_sources_disabled403noWebsite sources are switched off on the platform (details.scope = "platform") or for your organization (details.scope = "tenant"). Refused: adding a source, preview, sync, verification. Reading, pausing, deleting and resolving held runs keep working.
domain_blocked403noThe site's host, or a parent domain of it, is blocked on the platform (for example after a removal request from the site owner). Refused at preview, add, sync, resume and domain verification. details.domain is the blocked entry that matched.
domain_not_verified403noThe operation needs a verified domain: switching a sync schedule on or changing it, or, while the platform accepts verified sites only, syncing an unverified source or adding one with start_sync: true. details.domain, details.required = "verified_domain".
source_sync_in_progress409yes:sync while the source already has a queued, running or waiting run. details.run_id; retry_after_seconds = 60.
invalid_source_state409noNot allowed in the source's or run's current state: syncing a paused, held, blocked_by_site, disabled_by_admin or deleting source, or while an earlier held run is unresolved (details.status_reason = deletion_threshold); a status change that is not allowed; resolving a run that is not held, was already resolved with the other decision, or belongs to a deleting source. details.status, details.status_reason.
duplicate_source409noThe knowledge base already has a source (not being deleted) with the same normalised start URL and scope mode. details.existing_source_id.
https_required422noThe start URL uses http://. Website sources are https-only on port 443; details.suggested_url is the same URL with https://.
source_url_rejected422noThe start URL breaks the URL rules: another scheme, a user name or password, a port other than 443, an IP address, a single-label or internal host name, more than 2,048 characters, or a host that resolves to a non-public address. details.rule; the URL is never echoed.
robots_disallowed422noAdding with a preview_id whose preview found the start URL disallowed by robots.txt for InfusBot, or robots.txt failing with a server error or unreachable (which counts as a full disallow). Refused whatever start_sync says: domain verification never overrides robots.txt. details.robots_status.
ai_signal_optout422noAdding with start_sync: true and a preview_id whose preview found an AI-usage opt-out on an unverified domain. Add it with start_sync: false and verify the domain first if it is your site. details.signals[] (source, value).
attestation_required422noAdding a source without attestation, with accepted other than true, or with a text_version that is not the current one. details.current_text_version.
terms_acceptance_required422noYour organization has not accepted the current website-source terms and the request carried no terms_acceptance for them (first source, or after the terms changed). details.current_terms_version, details.terms_url.

Rate and availability​

CodeHTTPRetryWhen
rate_limited429yesQuery or upload rate limit; for website sources also previews per hour (limit_name: web.previews_per_hour), a manual sync sooner than the cooldown after the previous run of the same source (limit_name: web.manual_sync_cooldown_minutes), or more than 30 domain verification checks per clock hour (limit_name: web.verifications_per_hour). In front of these, previews and syncs are also limited per organization to a short burst, 10 calls per operation per rolling minute by default (limit_name: gateway.web_previews_per_minute for POST …/sources:preview, gateway.web_syncs_per_minute for POST …/sources/{source_id}:sync); API keys and portal users of the organization share this limit. retry_after_seconds.
concurrency_limited429yesToo many concurrent processing jobs or exports.
internal_error500yesUnexpected failure.
maintenance_mode503yesPlatform maintenance: uploads, replacements, retries and exports paused; search, chat, download and delete work. retry_after_seconds = 300.
knowledge_unavailable503yesKnowledge bases could not be reached (temporary). A chat request with knowledge_base_ids fails with this — it never falls back to an answer without sources. Creating a knowledge base also gets this (details.reason: check_failed) when its embedding model cannot be checked right now; no knowledge base is created — retry after retry_after_seconds.
retrieval_unavailable503yesThe search index or the embedding model failed during search or retrieval.
billing_unavailable503yesBilling could not be reached: uploads, file replacements and retries are refused rather than run unbilled. By default a search or a grounded chat is not refused for this reason: it is served, and its query charge is settled once billing answers again (a platform operator can switch this off, and searches then get this code too). This applies only when billing gave no answer (unreachable, timeout or a 5xx). Searches still get this code when billing did answer but the answer cannot be used (a refusal the platform cannot map, a malformed answer or a 4xx), or when your organization's usage records are more than 15 minutes behind (details.reason: measurement_debt, retry_after_seconds = 60).

Document failure codes​

A failed document's failure (and the knowledge.document.failed webhook) is {code, message, retryable}. Besides the "document" codes above:

CodeMeaningretryable
processing_failedPlatform failure after 5 automatic retries. Not charged.yes — POST …/retry
processing_budget_exceededThe actual processing cost would exceed the upload's max_processing_cost.no
awaiting_budget_timeoutThe document waited 24 h in awaiting_budget without a paid allowance; the temporary file was removed.yes — upload again

Billing refusals during processing (trial_exhausted, insufficient_credits, credit_limit_exceeded, payg_spend_cap_exceeded) do not fail a document: it moves to awaiting_budget with failure explaining why, and continues as soon as an allowance is available.

For website pages, storage refusals wait in awaiting_budget the same way (a page's storage is checked when it is processed, not when it is fetched). payment_suspended cannot be solved by waiting: the page is not indexed, nothing is charged, and its run ends failed with stop_reason: billing_blocked.

Retry guidance​

  • retryable: false → do not retry unchanged.
  • 429 and 503 → honour Retry-After; otherwise back off exponentially from 1 s, capped at 60 s, with jitter.
  • 409 idempotency_in_progress → retry the same request with the same key after Retry-After.
  • Every POST that creates work accepts Idempotency-Key; retrying with the same key is always safe and never charges twice.