RAG Service
API Docs Center
← Back to Documentation Center

Error Handling & Error Codes

This page provides a high-level overview. For the canonical v2 template status codes and payload shape, see Templates → V2 → Status Codes.

Standard HTTP Status Codes (overview)

Status Name When it happens Retry?
400 Bad Request Invalid input, missing required fields, bad parameters No, fix request
401 Unauthorized Missing/invalid API key or JWT After fixing auth
403 Forbidden Authenticated but not authorized No, check permissions
404 Not Found Resource or route does not exist (e.g., bad upload_id) No
409 Conflict Duplicate resource or operation conflict (e.g., duplicate upload when prevent_reprocess=true) Sometimes, after resolving conflict
413 Payload Too Large Request/upload exceeds size limits No, reduce size
415 Unsupported Media Type Content-Type not supported No, change type
422 Unprocessable Entity Validation failed (schema/field-level) No, fix request
429 Too Many Requests Rate-limited by upstream or API Yes, with backoff
500 Internal Server Error Unexpected failure Maybe, if transient
502 Bad Gateway Upstream LLM/service error Yes, transient likely
503 Service Unavailable Dependency unavailable or overload Yes, transient
504 Gateway Timeout Upstream timeout Yes, transient

Notes: - Upload endpoints commonly use 400, 401, 409, 500. - Chat/Flexible RAG endpoints commonly use 400, 401, 500. Upstream issues surface as 502/503/504.

Error Payload Schema (overview)

All error responses use a structured JSON body. Fields may vary by endpoint, but the core shape is stable.

{
    "error": {
        "message": string,              // human-readable summary
        "code": string | null,          // optional domain or SDK-specific code
        "status_code": number,          // HTTP status
        "details": object | null,       // extra context (validation errors, hints)
        "request_id": string | null,    // x-ms-request-id or similar if available
        "trace_id": string | null,      // traceparent/span id if available
        "upstream": {                   // present when an upstream service failed
            "service": string,            // e.g., "azure_openai", "ai_search"
            "status_code": number | null,
            "code": string | null,
            "message": string | null
        }
    }
}

Implementation notes: - We enrich error payloads with selected headers (x-ms-request-id, traceparent) and nested SDK error codes when present. - Validation errors may include a details object with per-field messages.

Examples (overview)

400 Bad Request (validation)

{
    "error": {
        "message": "'question' is required",
        "code": "validation_error",
        "status_code": 400,
        "details": { "question": "field required" },
        "request_id": null,
        "trace_id": null
    }
}

409 Conflict (duplicate upload)

{
    "error": {
        "message": "File already processed for this index",
        "code": "duplicate",
        "status_code": 409,
        "details": { "prevent_reprocess": true }
    }
}

502 Bad Gateway (upstream LLM)

{
    "error": {
        "message": "Azure OpenAI returned an error",
        "code": "upstream_error",
        "status_code": 502,
        "upstream": {
            "service": "azure_openai",
            "status_code": 429,
            "code": "rate_limit_exceeded",
            "message": "Requests to the embeddings endpoint are rate limited"
        },
        "request_id": "f8c4a...",
        "trace_id": "00-7c5...-01"
    }
}

Troubleshooting

  • 400/422: Check required fields and schema. See each endpoint’s request schema under Schemas.
  • 401/403: Verify API key and JWT configuration. Ensure roles/claims permit the action.
  • 409: Resolve the conflict (toggle prevent_reprocess, change target, or replace).
  • 413/415: Reduce payload size or change Content-Type to a supported value.
  • 429/502/503/504: Transient or capacity issues. Implement retries with exponential backoff.
  • 500: Check logs and health endpoints. If persistent, file an issue with request_id/trace_id.

See Also

  • Upload errors: upload page (Error Handling & Status Codes)
  • Chat/Flexible RAG errors: chat and flexible_rag pages
  • Developer deep-dive: docs/developer/endpoints/health.dev.md (error enrichment)