Lỗi, giới hạn và thử lại

Mọi API Felo trả về nội dung lỗi JSON với mã lỗi ổn định và một request ID. Hãy đọc trạng thái HTTP trước, rồi đến mã, sau đó đến thông điệp.

Cấu trúc lỗi

Các phản hồi production hiện tại dùng trạng thái HTTP làm status:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid API Key",
  "request_id": "202610221444486982113280416060637185"
}

Một số ví dụ endpoint cũ dùng status: "error" và một chuỗi mã khác. Hãy phân nhánh theo trạng thái HTTP và code, không dựa vào nội dung chính xác của message.

Mã thường gặp

Các tham chiếu endpoint liệt kê những mã riêng của endpoint đó. Hãy bắt đầu với lỗi Chat API hoặc tham chiếu cho endpoint bạn đang gọi.

Các endpoint tạo sinh mô hình

POST /api/v1/images/generations và POST /api/v1/videos/generations trả về lỗi cấp endpoint theo cấu trúc của OpenAI thay vì cấu trúc ở trên:

{
  "error": {
    "message": "Model kind does not match this generation endpoint",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_kind_mismatch"
  }
}

Request ID nằm trong header phản hồi X-Request-Id, không nằm trong nội dung. Một yêu cầu bị từ chối không tạo tác vụ. Khi tác vụ đã tồn tại, hầu hết thất bại đến dưới dạng trạng thái tác vụ kết thúc trong phản hồi 200 thay vì lỗi HTTP: kiểm tra status là failed hoặc interrupted, rồi đọc error.message. Xem Tạo hình ảnh và Tác vụ bất đồng bộ.

Request ID

Nội dung lỗi của Felo bao gồm request_id. Hãy ghi nó cùng với endpoint, trạng thái HTTP, mã lỗi, model ID và task ID. Không bao giờ ghi toàn bộ khóa API vào nhật ký.

Model API cũng chấp nhận header yêu cầu X-Request-Id tùy chọn. Khi bạn gửi một giá trị, nó được trả lại để chẩn đoán, giúp bạn đối chiếu nhật ký của mình với một yêu cầu. Nếu bạn không gửi, hãy dùng request_id được trả về.

Giới hạn tần suất

/v2/chat là endpoint Felo duy nhất có giới hạn tần suất được áp dụng và ghi trong tài liệu:

• Theo khóa API, cửa sổ 1 phút.
• Theo người dùng, cửa sổ 1 phút.
• Theo người dùng, cửa sổ 1 giờ.

Người dùng có gói đăng ký Felo trả phí đang hiệu lực, bao gồm gói doanh nghiệp, được miễn và không nhận header X-RateLimit-*. Nếu không thể xác minh trạng thái đăng ký, các giới hạn vẫn được áp dụng.

Các endpoint /v2/** khác hiện không có giới hạn tần suất được áp dụng. Các yêu cầu Model API vẫn có thể bị nhà cung cấp thượng nguồn giới hạn, điều này có thể xuất hiện dưới dạng 429.

Không gán cứng các giới hạn số. Hãy đọc header trên từng phản hồi.

Chính sách thử lại

Vòng lặp được khuyến nghị:

1. Chỉ thử lại các yêu cầu idempotent hoặc an toàn khi lặp lại.
2. Dùng thời gian chờ tăng dần theo cấp số nhân: bắt đầu khoảng 1 giây, gấp đôi mỗi lần, tối đa 30 giây.
3. Thêm độ trễ ngẫu nhiên để các máy khách không thử lại đồng loạt.
4. Dừng sau một số lần thử nhỏ và báo lỗi ra ngoài.
5. Với 429, hãy tuân theo Retry-After thay vì lịch của riêng bạn.

Trình tự gỡ lỗi

1. Kiểm tra khóa có tồn tại và chưa bị thu hồi.
2. Gọi GET /api/v1/models với cùng khóa để xác nhận xác thực.
3. Gửi yêu cầu hợp lệ nhỏ nhất đến endpoint đích.
4. Thêm streaming, tools hoặc đầu vào lớn lần lượt từng thứ.
5. Với công việc bất đồng bộ, kiểm tra trạng thái tác vụ trước khi gửi lại.

Liên quan

• Xác thực
• Kênh và định tuyến nhà cung cấp
• Tác vụ bất đồng bộ
• Khắc phục sự cố