Lỗi - OrcaRouter

Envelope lỗi

Hầu hết các phản hồi lỗi dùng định dạng JSON tương thích OpenAI:

{
  "error": {
    "message": "Descriptive error message",
    "type": "orcarouter_api_error",
    "code": "model_not_found"
  }
}

type là một danh mục rộng, code là một định danh cụ thể. Một số thất bại đường nhanh (đáng chú ý là 429 cấp workspace) chỉ trả về mã trạng thái HTTP với các header liên quan và không có thân JSON.

Mã trạng thái HTTP

Status	Ý nghĩa	Nguyên nhân điển hình
`400`	Yêu cầu sai	Tham số không hợp lệ, thiếu trường bắt buộc, vi phạm lược đồ
`401`	Chưa xác thực	Thiếu hoặc khóa API không hợp lệ
`403`	Cấm	Hết hạn mức, hoặc khóa không thể gọi mô hình này
`404`	Không tìm thấy	Mô hình hoặc endpoint không tồn tại
`429`	Quá nhiều yêu cầu	Đụng giới hạn tốc độ — xem Giới hạn tốc độ. Phản hồi luôn bao gồm header `Retry-After`.
`500`	Lỗi nội bộ	Lỗi phía OrcaRouter
`502`	Lỗi upstream	Tất cả nhà cung cấp upstream thất bại (bao gồm mọi chuỗi dự phòng)
`503`	Dịch vụ không khả dụng	Mô hình yêu cầu tạm thời không khả dụng tại upstream

Các loại lỗi bạn có thể thấy trong `error.type`

`error.type`	Đến từ đâu
`orcarouter_api_error`	Lỗi phía gateway (xác thực, hạn mức, giới hạn tốc độ, nội bộ)
`upstream_error`	Nhà cung cấp upstream trả lỗi hoặc hết giờ
`openai_error`	Lỗi upstream tương thích OpenAI được giữ nguyên
`claude_error`	Lỗi upstream Anthropic được giữ nguyên
`gemini_error`	Lỗi upstream Gemini được giữ nguyên

Các mã lỗi bạn có thể thấy trong `error.code`

Đây là các mã do gateway phát sinh cho các thất bại bắt nguồn từ OrcaRouter (không phải upstream):

`error.code`	HTTP	Ý nghĩa
`insufficient_user_quota`	403	Đã hết tín dụng tài khoản. Hãy nạp thêm.
`model_not_found`	503	Mô hình này không khả dụng cho tài khoản của bạn.
`model_price_error`	400	Giá cho mô hình này chưa được thiết lập. Liên hệ hỗ trợ.
`api_not_implemented`	400	Endpoint hoặc thao tác không được hỗ trợ cho mô hình bạn đã chọn.
`bad_request_body`	400	Thân yêu cầu không thể phân tích được.
`prompt_blocked`	400	Chính sách an toàn của nhà cung cấp đã chặn prompt trước khi sinh.
`sensitive_words_detected`	400	Bộ lọc nội dung nhạy cảm đã từ chối prompt.

Nếu bạn cần phân biệt theo chương trình, hãy khớp theo error.code trước (cụ thể) rồi dự phòng theo error.type (danh mục rộng).

Lỗi khi streaming

Các lỗi trong phản hồi streamed không thể dùng mã trạng thái HTTP (trạng thái đã được gửi khi luồng mở). Định dạng phụ thuộc vào endpoint:

`/v1/chat/completions` và `/v1/responses` (tương thích OpenAI)

Lỗi đến như một chunk data: {...} trong luồng:

data: {"error":{"message":"...","type":"upstream_error","code":""}}

data: [DONE]

Phân tích mỗi chunk data: thành JSON; nếu có trường error, coi luồng là thất bại.

`/v1/messages` (tương thích Anthropic)

Anthropic dùng sự kiện SSE có tên. Một thất bại trong luồng đến như:

event: error
data: {"type":"error","error":{"type":"overloaded_error","message":"..."}}

Luồng kết thúc với event: message_stop (hoặc bị cắt) sau sự kiện lỗi.

Lỗi dự phòng

Khi extra_body.models được đặt và mọi mô hình trong chuỗi đều thất bại, bạn nhận 502 với chi tiết về lỗi upstream cuối cùng. Các header phản hồi X-Orca-Fallback-Level và X-Orca-Fallback-Model cho biết dự phòng nào đang được thử khi chuỗi cạn. Xem Header phản hồi.

​Envelope lỗi

​Mã trạng thái HTTP

​Các loại lỗi bạn có thể thấy trong error.type

​Các mã lỗi bạn có thể thấy trong error.code

​Lỗi khi streaming

​/v1/chat/completions và /v1/responses (tương thích OpenAI)

​/v1/messages (tương thích Anthropic)

​Lỗi dự phòng