Knowledge
Errors
HTTP errors and asynchronous ingestion failures.
| HTTP | code | Action |
|---|---|---|
| 400 | INVALID_PARAMS | Invalid fields, filters or pagination. |
| 400 | LIMIT_EXCEEDED | Capacity or batch limit exceeded. |
| 401 | UNAUTHENTICATED | Check the API Key; compatible code is null. |
| 404 | VECTOR_STORE_NOT_FOUND | Knowledge base is missing or inaccessible. |
| 404 | FILE_NOT_FOUND | Source file does not exist. |
| 404 | FILE_NOT_IN_STORE | File is not in this knowledge base. |
| 404 | BATCH_NOT_FOUND | Batch does not exist. |
| 404 | CHUNK_NOT_FOUND | Segment does not exist. |
| 409 | VECTOR_STORE_INVALID_STATE | Operation is not allowed in the current store state. |
| 409 | FILE_INVALID_STATE | Only failed files can be retried. |
| 413 | PAYLOAD_TOO_LARGE | JSON body exceeds 1,000,000 bytes; compatible code can be null. |
| 429 | RATE_LIMITED | Retry later. |
| 500 | — / null | Internal error; retain the request ID and retry later. |
| 501 | NOT_IMPLEMENTED | Operation is not implemented. |
| 503 | PROVIDER_UNAVAILABLE | Processing service is temporarily unavailable; retry later. |
Native error object
| Field | Type | Description |
|---|---|---|
| error | object | required |
| error.code | "INVALID_PARAMS" / "LIMIT_EXCEEDED" / "UNAUTHENTICATED" / "VECTOR_STORE_NOT_FOUND" / "FILE_NOT_FOUND" / "FILE_NOT_IN_STORE" / "BATCH_NOT_FOUND" / "CHUNK_NOT_FOUND" / "VECTOR_STORE_INVALID_STATE" / "FILE_INVALID_STATE" / "PAYLOAD_TOO_LARGE" / "RATE_LIMITED" / "NOT_IMPLEMENTED" / "PROVIDER_UNAVAILABLE" | optional |
| error.message | string | required |
| error.details | string / null | optional |
OpenAI-compatible error object
| Field | Type | Description |
|---|---|---|
| error | object | required |
| error.message | string | required |
| error.type | "invalid_request_error" / "not_found_error" / "rate_limit_error" / "server_error" | required |
| error.param | string / null | required |
| error.code | "INVALID_PARAMS" / "LIMIT_EXCEEDED" / "UNAUTHENTICATED" / "VECTOR_STORE_NOT_FOUND" / "FILE_NOT_FOUND" / "FILE_NOT_IN_STORE" / "BATCH_NOT_FOUND" / "CHUNK_NOT_FOUND" / "VECTOR_STORE_INVALID_STATE" / "FILE_INVALID_STATE" / "PAYLOAD_TOO_LARGE" / "RATE_LIMITED" / "NOT_IMPLEMENTED" / "PROVIDER_UNAVAILABLE" / null | required |
Unknown-route 404 responses can contain only error.message; 401 can omit details, and compatible 413 can return code: null. Invalid URL encoding can also return HTML. Do not assume every failure has an error code.
Asynchronous file errors
A successful attachment does not mean the content is searchable. Check file status and read last_error when it is failed.
| last_error.code | Meaning | Action |
|---|---|---|
| unsupported_file | Parser does not support this file | Convert to TXT, Markdown or a verified format |
| invalid_file | Invalid, empty, encrypted or over the estimated token limit | Check, decrypt or split the file |
| server_error | Processing failed or exceeded 30 minutes | Retry the failed file later |