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" }
}
}
| Field | Rule |
|---|
code | Stable 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. |
type | Derived 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). |
message | English, for display. It never contains your content (file names, metadata values, query or chunk text). |
param | The offending field when there is one (metadata.department, filter.must[0].key, files[3]), otherwise null. |
request_id | Correlation id; quote it when contacting support. |
retryable | true only when the same request can succeed later without changes. |
retry_after_seconds | Set on 429, 503 and retryable 409s; mirrored in the Retry-After header. |
details | Code-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
| Code | HTTP | Retry | When / details |
|---|
scope_missing | 403 | no | The API key lacks knowledge:read / knowledge:write (or inference:chat for chat). details.required_scope. |
kb_not_in_allowlist | 403 | no | The 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_insufficient | 403 | no | A portal member without the admin or owner role attempted a change. details.required_role. |
actor_not_permitted | 403 | no | This kind of caller cannot use the route. |
tenant_suspended | 403 | no | Your organization is suspended. |
not_found | 404 | no | Absent, 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_disabled | 404 / 403 | no | Knowledge 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_expired | 410 | no | The 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.
| Code | Retry | When / details |
|---|
trial_exhausted | no | A 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_credits | no | The prepaid wallet cannot hold the amount. |
credit_limit_exceeded | no | The postpaid credit limit would be exceeded. |
payg_spend_cap_exceeded | no | The 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_suspended | no | Paid work stopped because of a payment problem. details.suspended_at, details.deletion_at. Download and delete stay open. |
State conflicts (409)
| Code | Retry | When / details |
|---|
idempotency_key_conflict | no | The same Idempotency-Key was used within 24 h with a different request. |
idempotency_in_progress | yes | The original request with this key is still running. Retry the same request with the same key after Retry-After (≈2 s). |
version_conflict | no | A file replacement is already running for this document. |
duplicate_content | no | The same content is already in this knowledge base and on_duplicate=reject. details.existing_document_id. |
kb_suspended | no | The knowledge base is suspended because of a payment problem (details.reason: payment_suspended). Search and upload closed; list, download, export, delete open. |
kb_deleting | no | The knowledge base is being deleted. |
document_deleting | no | The document is being deleted. |
document_not_ready | no | /content or /chunks on a document without a ready version. |
invalid_document_state | no | retry 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_frozen | no | Idle free-trial knowledge base. details.frozen_at, details.deletion_at. |
resource_limit_reached | no | Knowledge 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_progress | yes | An export for this knowledge base is already running. details.export_id. |
Size (413)
| Code | When / details |
|---|
file_too_large | A file exceeds 50 MB (details.max_bytes). Per file in multi-file uploads; for the whole request on a file replacement. |
too_many_files | More than 50 files in one upload request. |
request_too_large | Upload body above 500 MB, or a JSON body above 1 MB. |
Validation (422)
| Code | Where | When |
|---|
validation_failed | request | Schema 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_identifier | request | A path or body id is not a UUID. |
metadata_key_reserved | request | Metadata key collides with a platform field. |
metadata_too_many_keys | request | More than 16 metadata keys after the change. |
metadata_invalid_key | request | Key does not match ^[a-z][a-z0-9_]{0,63}$. |
metadata_invalid_value | request | Not a string ≤256 characters, finite number, boolean or date; or null/array/object. |
filter_invalid | request | Malformed filter — see Filters. |
too_many_knowledge_bases | request | More than 5 knowledge bases in one chat request. |
query_too_long | request | Search query longer than 2,000 characters. |
retrieval_query_missing | request | Chat with knowledge_base_ids whose last message is not a user message with text. |
tools_not_supported_with_knowledge | request | Chat combines knowledge_base_ids with tools or functions. |
batch_too_large | request | More than 100 ids in a batch operation. |
unsupported_file_type | upload, document | Not PDF, DOCX, PPTX, XLSX, CSV, HTML, TXT or MD. |
file_type_mismatch | upload, document | Extension, MIME type and file signature disagree. |
corrupt_file | upload, document | Structurally unreadable. |
encrypted_file | upload, document | Password-protected or encrypted. |
macro_file | upload, document | Office file containing macros. |
archive_bomb | upload, document | DOCX/PPTX/XLSX expands beyond the size or entry ceiling. |
no_text_content | document | No extractable text (scanned PDF; no OCR). |
extraction_limit_exceeded | document | Extracted 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_exceeded | document | Processing 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.
| Code | HTTP | Retry | When / details |
|---|
web_sources_disabled | 403 | no | Website 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_blocked | 403 | no | The 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_verified | 403 | no | The 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_progress | 409 | yes | :sync while the source already has a queued, running or waiting run. details.run_id; retry_after_seconds = 60. |
invalid_source_state | 409 | no | Not 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_source | 409 | no | The knowledge base already has a source (not being deleted) with the same normalised start URL and scope mode. details.existing_source_id. |
https_required | 422 | no | The start URL uses http://. Website sources are https-only on port 443; details.suggested_url is the same URL with https://. |
source_url_rejected | 422 | no | The 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_disallowed | 422 | no | Adding 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_optout | 422 | no | Adding 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_required | 422 | no | Adding 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_required | 422 | no | Your 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
| Code | HTTP | Retry | When |
|---|
rate_limited | 429 | yes | Query 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_limited | 429 | yes | Too many concurrent processing jobs or exports. |
internal_error | 500 | yes | Unexpected failure. |
maintenance_mode | 503 | yes | Platform maintenance: uploads, replacements, retries and exports paused; search, chat, download and delete work. retry_after_seconds = 300. |
knowledge_unavailable | 503 | yes | Knowledge 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_unavailable | 503 | yes | The search index or the embedding model failed during search or retrieval. |
billing_unavailable | 503 | yes | Billing 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:
| Code | Meaning | retryable |
|---|
processing_failed | Platform failure after 5 automatic retries. Not charged. | yes — POST …/retry |
processing_budget_exceeded | The actual processing cost would exceed the upload's max_processing_cost. | no |
awaiting_budget_timeout | The 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.