API error responses and handling recommendations
All error responses follow a consistent structure:
Every response includes a
HTTP Status Codes
| Status Code | Meaning | Recommended Action |
|---|---|---|
| 400 | Invalid request parameters | Validate request parameters |
| 401 | Authentication failed | Verify your API Key |
| 403 | Insufficient permissions | Request appropriate permission scope |
| 404 | Resource not found | Verify the resource ID |
| 409 | Resource conflict | Typically caused by duplicate names |
| 413 | Request payload too large | Split the request into smaller parts |
| 429 | Rate limited | Implement exponential backoff retry logic |
| 500 | Internal server error | Retry; if failures persist, contact support |
| 503 | Service unavailable | Implement exponential backoff retry logic |
Business Error Codes
| Code | HTTP | Description |
|---|---|---|
| INVALID_PARAMETER | 400 | Missing or malformed parameter |
| UNAUTHORIZED | 401 | API Key missing or invalid |
| FORBIDDEN | 403 | Insufficient permissions to perform the operation |
| KB_NOT_FOUND | 404 | Knowledge base does not exist |
| DOCUMENT_NOT_FOUND | 404 | Document does not exist |
| DATA_SOURCE_NOT_FOUND | 404 | Data source does not exist |
| KB_NAME_CONFLICT | 409 | Knowledge base name already exists |
| QUOTA_EXCEEDED | 429 | Tenant quota exceeded |
| RATE_LIMITED | 429 | API rate limit exceeded |
| EMBEDDING_FAILED | 500 | Embedding service error |
| RETRIEVAL_TIMEOUT | 504 | Retrieval timed out — reduce top_k or enable a smaller reranking model |
| SYNC_SOURCE_UNREACHABLE | 502 | Failed to connect to data source |
Retry Strategy
| Error Type | Retry? | Interval |
|---|---|---|
| 4xx (except 429) | No | — |
| 429 (rate limiting) | Yes | Use value from Retry-After header, or apply exponential backoff: 1s → 2s → 4s |
| 5xx | Yes | Exponential backoff: 1s → 2s → 4s, maximum 3 attempts |
| 504 (timeout) | Yes | Immediate retry, maximum 2 attempts |
Troubleshooting
Every response includes a request_id. When contacting support, include this ID to help us quickly locate relevant logs.