Skip to main content

Error Codes

API error responses and handling recommendations

All error responses follow a consistent structure: 
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Field knowledge_base_id cannot be empty",
    "param": "knowledge_base_id"
  },
  "request_id": "req_xxx"
}

HTTP Status Codes

Status CodeMeaningRecommended Action
400Invalid request parametersValidate request parameters
401Authentication failedVerify your API Key
403Insufficient permissionsRequest appropriate permission scope
404Resource not foundVerify the resource ID
409Resource conflictTypically caused by duplicate names
413Request payload too largeSplit the request into smaller parts
429Rate limitedImplement exponential backoff retry logic
500Internal server errorRetry
503Service unavailableImplement exponential backoff retry logic

Business Error Codes

CodeHTTPDescription
INVALID_PARAMETER400Missing or malformed parameter
UNAUTHORIZED401API Key missing or invalid
FORBIDDEN403Insufficient permissions to perform the operation
KB_NOT_FOUND404Knowledge base does not exist
DOCUMENT_NOT_FOUND404Document does not exist
DATA_SOURCE_NOT_FOUND404Data source does not exist
KB_NAME_CONFLICT409Knowledge base name already exists
QUOTA_EXCEEDED429Tenant quota exceeded
RATE_LIMITED429API rate limit exceeded
EMBEDDING_FAILED500Embedding service error
RETRIEVAL_TIMEOUT504Retrieval timed out — reduce top_k or enable a smaller reranking model
SYNC_SOURCE_UNREACHABLE502Failed to connect to data source

Retry Strategy

Error TypeRetry?Interval
4xx (except 429)No—
429 (rate limiting)YesUse value from Retry-After header, or apply exponential backoff: 1s → 2s → 4s
5xxYesExponential backoff: 1s → 2s → 4s, maximum 3 attempts
504 (timeout)YesImmediate retry, maximum 2 attempts

Troubleshooting

Every response includes a request_id, which helps locate the relevant logs quickly.
Explore specific endpoints—start with List Knowledge Bases.