Mã lỗi và giới hạn của API Gateway

Khi một yêu cầu không thành công, API Gateway trả mã HTTP kèm thân JSON theo dạng OpenAI. Đọc trường code để biết chính xác nguyên nhân.

#Định dạng lỗi

{
  "error": {
    "message": "Insufficient credit. Top up via VietQR at your dashboard billing page to continue using the API.",
    "type": "billing_error",
    "code": "insufficient_credit"
  }
}

• message — mô tả bằng tiếng Anh.
• type — nhóm lỗi, ví dụ authentication_error, billing_error, permission_error.
• code — mã chi tiết, dùng để xử lý trong mã nguồn.

Thông báo lỗi từ nhà cung cấp phía sau được làm sạch trước khi trả về, nên bạn không thấy tên nhà cung cấp hay URL nội bộ.

#Lỗi xác thực và quyền

#Lỗi thanh toán

Lỗi 402 kèm trường recovery_url trỏ tới trang thanh toán. Xem Sử dụng & thanh toán để nạp credit hoặc gia hạn.

#Giới hạn và lỗi 429

API Gateway áp dụng các giới hạn sau:

• Ngân sách cửa sổ của gói — mỗi gói có ngân sách theo cửa sổ 5 giờ hoặc 24 giờ. Hết ngân sách, yêu cầu nhận 429 mã plan_usage_window_limit; thông báo cho biết thời điểm đặt lại (Resets at …).
• Giới hạn chi tiêu ngày/tháng — nếu bạn đặt mức chi tiêu tối đa, vượt mức nhận 429 mã daily_spending_limit hoặc monthly_spending_limit.
• RPM — số yêu cầu mỗi phút theo gói, hiển thị ở dòng RPM trong thẻ Hạn mức gói.
• Số khoá — số khoá đang hoạt động tối đa theo gói. Tạo vượt mức nhận 403 mã key_limit_reached.

#Lỗi yêu cầu và máy chủ

Với 503, hãy chạy Health Check ở API Gateway › Model để xem model có đang Không phản hồi không.

#Xử lý lỗi trong ứng dụng

1. Phân loại theo mã HTTP

   Không thử lại với 400, 401, 402, 403: lỗi sẽ lặp lại cho tới khi bạn sửa yêu cầu, khoá hoặc tài khoản.

2. Thử lại có giãn cách với 429 và 5xx

   Đọc header Retry-After nếu có. Nếu không có, chờ tăng dần (1 giây, 2 giây, 4 giây…) và giới hạn số lần thử.

3. Kiểm tra bảng điều khiển

   Xem API Gateway › Tổng quan để biết hạn mức còn lại, và Sử dụng › Lịch sử để đối chiếu yêu cầu.

async function callWithRetry(fn: () => Promise<Response>, max = 4) {
  for (let i = 0; ; i++) {
    const res = await fn();
    if (res.ok || i >= max || (res.status !== 429 && res.status < 500)) return res;
    const wait = Number(res.headers.get("Retry-After")) || 2 ** i;
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
}

#Liên quan