RAG API error responses, HTTP status codes, business error codes, and retry strategy.
Every error response uses the same structure:
Every response includes a
HTTP status codes
| Status | Meaning | What to do |
|---|---|---|
| 400 | Invalid request parameter | Verify the parameter |
| 401 | Authentication failed | Check your API key |
| 403 | Forbidden | Request the appropriate permission scope |
| 404 | Resource not found | Verify the ID |
| 409 | Resource conflict | Usually a duplicate name |
| 413 | Request body too large | Split the request |
| 429 | Rate limited | Back off and retry |
| 500 | Internal server error | Retry; contact support if it persists |
| 503 | Service unavailable | Back off and retry |
Business error codes
| code | HTTP | Meaning |
|---|---|---|
| INVALID_PARAMETER | 400 | Parameter missing or malformed |
| UNAUTHORIZED | 401 | API key missing or invalid |
| FORBIDDEN | 403 | No permission for this operation |
| KB_NOT_FOUND | 404 | Knowledge Base not found |
| DOCUMENT_NOT_FOUND | 404 | Document not found |
| DATA_SOURCE_NOT_FOUND | 404 | Data source not found |
| KB_NAME_CONFLICT | 409 | Knowledge Base name already exists |
| QUOTA_EXCEEDED | 429 | Tenant quota exceeded |
| RATE_LIMITED | 429 | Endpoint rate limit hit |
| EMBEDDING_FAILED | 500 | Embedding service error |
| RETRIEVAL_TIMEOUT | 504 | Retrieval timed out — lower top_k or use a smaller Rerank model |
| SYNC_SOURCE_UNREACHABLE | 502 | Data source connection failed |
Retry strategy
| Error type | Retry? | Interval |
|---|---|---|
| 4xx (except rate limits) | No | — |
| 429 rate limited | Yes | Honor the Retry-After header, or back off 1s / 2s / 4s |
| 5xx | Yes | 1s / 2s / 4s, up to 3 retries |
| 504 timeout | Yes | Retry immediately, up to 2 times |
Troubleshooting
Every response includes a request_id. Include it when contacting support — it pinpoints the request in our logs.