Trước khi báo cáo Bug

Nếu có gì đó không hoạt động, cách nhanh nhất để biết lỗi nằm ở phía bạn hay phía chúng tôi là chạy cùng một yêu cầu từ một công cụ khác.

Khoảng 9 trên 10 báo cáo "API bị lỗi" hóa ra là do cấu hình sai base URL, API key cũ, tên model sai, hoặc cấu trúc request body từ một hướng dẫn đã lỗi thời ba phiên bản SDK.

Kiểm tra nhanh

Sao chép lệnh curl này vào terminal. Thay YOUR_KEY bằng API key của bạn từ dashboard rồi chạy. Nếu bạn nhận được kết quả completion bình thường, API key, mạng và backend của chúng tôi đều hoạt động tốt — bất kỳ lỗi nào là trong code client hoặc môi trường của bạn.

cURL

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "ping"}]
  }'

Danh sách kiểm tra từng bước

API key của bạn có hợp lệ không?

Mở Dashboard → API Keys và xác nhận key khớp với những gì code của bạn sử dụng. Một bẫy phổ biến là khoảng trắng trước tiền tố "sk-air-" do sao chép-dán.

Triệu chứng: 401 Unauthorized.

Base URL có đúng không?

Base URL phải là https://api.airforce/v1 — không phải http, và hậu tố /v1 là bắt buộc. Các hướng dẫn ra đời trước khi OpenAI có đường dẫn v1 đôi khi bỏ qua phần này.

Triệu chứng: 404 Not Found, hoặc curl bị treo.

Tên model có được viết đúng không?

Model ID phân biệt chữ hoa và thường. Truy cập trang Models hoặc gọi GET /v1/models để xác nhận ID chính xác. Lỗi đánh máy hoặc model đã bị ngừng hỗ trợ sẽ trả về lỗi rõ ràng thay vì "hoạt động nhưng sai".

Triệu chứng: 400 unknown_model hoặc 404 model_not_found.

Request body có đúng cấu trúc không?

Chat completions dùng mảng messages. Hình ảnh dùng prompt + n. Audio TTS dùng input + voice. Gửi body dạng chat đến /v1/images/generations sẽ trả về 400 — dễ bỏ sót khi sao chép đoạn code giữa các tài liệu.

Triệu chứng: 400 kèm tên trường vi phạm trong response body.

Bạn có vượt giới hạn tốc độ hoặc hạn mức không?

429 = quá nhiều yêu cầu trong phút này. 402 = gói hoặc số dư của bạn đã cạn. Cả hai đều hiển thị trên Dashboard. Yêu cầu gói miễn phí có giới hạn riêng so với yêu cầu gói trả phí, vì vậy một model trả phí có thể trả lời tốt trong khi model miễn phí bị giới hạn tốc độ.

Triệu chứng: 429 Too Many Requests hoặc 402 Payment Required.

Model có thực sự đang hoạt động không?

Kiểm tra trang Models — sự cố nhà cung cấp sẽ hiển thị là "degraded" hoặc "major outage". Nếu một model bị ngừng trong khi các model khác vẫn hoạt động, đó là sự cố từ phía nhà cung cấp mà chúng tôi định tuyến xung quanh, không phải lỗi client.

Triệu chứng: một model cụ thể trả về 5xx trong khi các model khác hoạt động.

Ý nghĩa các mã HTTP Status

Mỗi phản hồi lỗi đều mang một mã HTTP status chuẩn. Hiểu rõ từng mã sẽ giúp bạn tiết kiệm một ticket.

Khi nào thực sự là Bug

Nếu lệnh curl tự kiểm tra ở trên hoạt động nhưng cùng một yêu cầu từ code của bạn lại không, vấn đề nằm ở client của bạn (hoặc thư viện mà nó sử dụng). Nếu bản thân lệnh tự kiểm tra thất bại với 5xx, hoặc trả về 4xx với thông báo không khớp với yêu cầu của bạn, đó là điều đáng báo cáo.

Cách báo cáo hiệu quả

Mở ticket hỗ trợ từ dashboard hoặc đăng trong #support trên Discord. Đính kèm:

• Mã HTTP status đầy đủ và response body (cả header cf-ray nếu có).
• Thời điểm gần đúng theo UTC.
• Tên model và endpoint bạn đã gọi.
• Một lệnh cURL tối giản để tái hiện lỗi (che đi API key thật của bạn!).
• Lệnh tự kiểm tra ở trên có hoạt động với key đó không.

Hỏi trong #support trên Discord