Xử lý sự cố

Hãy bắt đầu từ triệu chứng, rồi làm theo cách khắc phục. Hầu hết thất bại đến từ base URL, khóa, model ID hoặc số dư.

Bảng theo triệu chứng

Xác thực

Khóa đã bị thu hồi trả về thông điệp nêu tiền tố của khóa:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "API Key has been revoked (keyPrefix=...)"
}

Danh sách kiểm tra:

• Header là Authorization: Bearer <key> cho Model API và các Felo API.
• Data API cũng chấp nhận X-API-Key: <key>.
• Khóa không bị bọc trong dấu ngoặc kép, và không có ký tự xuống dòng thừa do sao chép biến môi trường.
• Môi trường đã triển khai thực sự có biến được đặt; một khóa hoạt động cục bộ có thể bị thiếu ở production.
• Khóa chưa bị xóa hoặc xoay vòng. Khóa đã bị xóa hoặc xoay vòng không thể hiển thị lại; hãy tạo khóa mới.

Xem Xác thực để biết cách tạo khóa và các giới hạn.

Bẫy base URL

Hai lỗi thường gặp:

1. Thêm /chat/completions vào một base URL mà SDK đã tự nối thêm.
2. Đặt base URL của Anthropic thành https://openapi.felo.ai/api/v1. SDK nối thêm /v1/messages, nên yêu cầu trở thành /api/v1/v1/messages.

Vấn đề model ID

Model ID là các ID công khai từ danh mục, không phải tên nội bộ của nhà cung cấp thượng nguồn hay tên hiển thị.

• Tra ID trên trang mô hình hoặc trong GET /api/v1/models.
• Xác nhận mô hình hỗ trợ giao thức bạn đang gọi (supported_protocols).
• Nếu bạn đã ghim một kênh, hãy xác nhận kênh đó đã được công bố và đang chạy được cho mô hình đó. Một kênh không khả dụng không phải là phương án dự phòng.

Xem Kênh và định tuyến nhà cung cấp.

Vấn đề truyền trực tiếp

• Đặt stream: true trong nội dung yêu cầu, không phải dưới dạng tham số truy vấn.
• Đọc nội dung phản hồi dưới dạng luồng. Chờ toàn bộ phản hồi sẽ vô hiệu hóa lợi ích của truyền trực tiếp.
• Một số proxy và nền tảng serverless đệm phản hồi. Hãy tắt đệm cho tuyến proxy yêu cầu.
• Chat Completions truyền choices[0].delta, không phải choices[0].message. Nội dung cuối cùng đến qua nhiều chunk.
• Một luồng có thể kết thúc mà không có sự kiện kết thúc sạch nếu kết nối bị ngắt. Hãy coi kết nối bị ngắt là phản hồi chưa hoàn tất.

Vấn đề tác vụ bất đồng bộ

• Thăm dò endpoint trạng thái thuộc đúng nhóm tác vụ. Quy trình Felo dùng GET /v2/tasks/{task_id}/status; tác vụ video và hình ảnh của mô hình dùng endpoint tạo sinh riêng của chúng.
• Dừng ở mọi trạng thái kết thúc, bao gồm thất bại và hết hạn, không chỉ thành công.
• Callback của video và hình ảnh hiện bị bỏ qua. Không chờ webhook.
• URL kết quả có thể tồn tại trong thời gian ngắn. Hãy yêu cầu URL mới từ endpoint trạng thái nếu một lần tải xuống hết hạn.
• Kiểm tra tác vụ trước khi gửi lại. Gửi lại một tác vụ đang chạy sẽ tạo bản trùng lặp, và cả hai đều bị tính phí.

Xem Tác vụ bất đồng bộ.

Vấn đề Data API

• Giữ nguyên phương thức và đường dẫn chính xác từ tham chiếu Data API.
• Nội dung yêu cầu riêng theo nhà cung cấp. Một trường hoạt động với nhà cung cấp này không bảo đảm hoạt động với nhà cung cấp khác.
• Lỗi nhà cung cấp có thể đến trong một phản hồi 4xx với thông điệp riêng của nhà cung cấp. Hãy ghi lại request_id và nội dung phản hồi.

Nhắc nhở bảo mật

• Không bao giờ đặt khóa API trong mã trình duyệt, gói ứng dụng di động hoặc kho lưu trữ công khai. Hãy giữ nó trên máy chủ và proxy các yêu cầu.
• Không ghi toàn bộ khóa vào nhật ký. Ghi một tiền tố nếu bạn cần nhận diện khóa.
• Xoay vòng khóa ngay lập tức nếu khóa có thể đã bị lộ.

Trước khi liên hệ hỗ trợ

Hãy thu thập:

1. Endpoint và phương thức HTTP.
2. Trạng thái HTTP, code và request_id.
3. Model ID hoặc task ID.
4. Dấu thời gian kèm múi giờ.
5. Một nội dung yêu cầu tối giản đã loại bỏ thông tin bí mật.

Gửi cho hỗ trợ kèm email tài khoản. Không bao gồm toàn bộ khóa API.

Liên quan

• Lỗi, giới hạn và thử lại
• Giao thức và SDK
• Thanh toán và tín dụng
• Xác thực