Lỗi

Mọi phản hồi không phải 2xx đều có cùng cấu trúc JSON — theo tiêu chuẩn OpenAI. Dựa vào error.code để xử lý bằng chương trình và status_code để xác định chính sách thử lại.

Payload lỗi

{
  "error": {
    "message": "Model 'xyz-2025' is not available",
    "type": "model_not_found",
    "code": "model_not_found",
    "param": null
  }
}

Mã trạng thái HTTP

Hãy xem lỗi 5xx khi gửi yêu cầu như vậy là kết quả chưa xác định, không phải thất bại. Hãy gửi header Idempotency-Key trong mọi lần gửi yêu cầu như vậy: sau lỗi 5xx, gửi lại cùng yêu cầu với cùng khóa sẽ trả về tác vụ nếu đã có, và khởi chạy tác vụ nếu chưa có.

Lệnh gọi có phản hồi không bao giờ đến được với bạn cũng không phải là lệnh gọi thất bại. Yêu cầu đồng bộ chạy quá thời gian chờ của ứng dụng khách vẫn tiếp tục chạy đến hết và bị tính phí. Luồng mà bạn đóng sớm cũng vẫn chạy đến hết và bị tính phí cho toàn bộ phản hồi, không chỉ cho phần bạn đã đọc.

Các mã lỗi thường gặp

authentication_error

• Quên đặt tiêu đề Authorization: Bearer ....
• Khóa API đã bị thu hồi từ /app/keys.
• Khóa vẫn có tiền tố sai (phải bắt đầu bằng sk-kn-).

insufficient_quota

• Số dư ví quá thấp cho yêu cầu này → error.code là insufficient_balance, và lỗi chứa thông tin về số dư hiện có trong ví (balance_usd), khoản tiền yêu cầu này cần tạm giữ (needed_usd), cùng hai liên kết: topup_url mở trang thanh toán với khoản nạp tiền được chọn sẵn, còn auto_recharge_url mở trang tại phần cài đặt nạp tiền tự động. Bản thân hai liên kết này không tính phí.
• Đã chạm giới hạn hằng tháng của khóa. Giới hạn được đặt lại vào đầu tháng dương lịch (UTC). Tăng giới hạn tại /app/keys.

{
  "error": {
    "message": "Wallet balance is too low for this request. Top up at https://kunavo.com/app/billing. Once a top-up has been paid, you can also turn on auto-recharge there: a saved card then refills the wallet when its balance falls under a threshold you choose.",
    "type": "insufficient_quota",
    "code": "insufficient_balance",
    "param": null,
    "balance_usd": 0.0142,
    "needed_usd": 0.0381,
    "topup_url": "https://kunavo.com/app/billing?topup=20",
    "auto_recharge_url": "https://kunavo.com/app/billing?autorecharge=1&src=api_402"
  }
}

Phản hồi 402 do số dư ví có nghĩa là khoản tiền mà yêu cầu cần tạm giữ vượt quá balance_usd trừ đi khoản tiền mà các yêu cầu và tác vụ đang chạy tạm giữ. Khi tính năng nạp tiền tự động được bật, Kunavo sẽ nạp tiền vào ví trước bằng phương thức thanh toán đã lưu, nhưng chỉ khi balance_usd thấp hơn ngưỡng nạp tiền tự động mà bạn đặt và việc nạp tiền vẫn nằm trong các giới hạn nạp tiền, rồi thử lại yêu cầu thêm một lần. Nếu không có lần nạp nào được thực hiện hoặc số tiền nạp không đủ, yêu cầu sẽ bị từ chối, vì vậy bạn vẫn có thể nhận phản hồi 402 ngay cả khi tính năng nạp tiền tự động đang bật.

Ngừng thử lại khi gặp insufficient_balance, trừ khi phản hồi có tiêu đề Retry-After — tiêu đề này nghĩa là giao dịch nạp tiền tự động đang được thực hiện bằng thẻ đã lưu của bạn và cùng yêu cầu đó sẽ thành công sau vài giây.

GET /v1/balance trả về số dư ví, số tiền đang được tạm giữ cho các tác vụ vẫn đang chạy và phần còn lại của từng giới hạn hằng tháng. Bạn có thể gọi endpoint này bất cứ lúc nào: không cần có một yêu cầu bị từ chối mới xem được các số liệu này. Phản hồi 402 do chạm giới hạn hằng tháng không có balance_usd cũng như needed_usd: thông báo của phản hồi cho biết đã chạm giới hạn nào, còn endpoint này cho biết phần còn lại của từng giới hạn. Xem Số dư.

permission_error

• Khóa có danh sách IP cho phép và lệnh gọi của bạn đến từ một địa chỉ nằm ngoài danh sách đó. Thông báo nêu địa chỉ chúng tôi ghi nhận — hãy thêm địa chỉ đó (hoặc khối CIDR của nó) tại /app/keys, hoặc xóa hẳn danh sách IP cho phép để cho phép mọi địa chỉ.
• Chuyển một tác tử sang máy chủ mới, cổng NAT mới hoặc máy tính xách tay dùng mạng khác đều làm thay đổi địa chỉ đó. Khóa không có danh sách IP cho phép sẽ không bao giờ bị từ chối theo cách này.

model_not_found

• Slug viết sai. Dùng /models để xem danh sách chuẩn.
• Model hiện đang bị tắt (do sự cố thượng nguồn hoặc đang xem xét giá).

upstream_error

Cho biết nhà cung cấp model thượng nguồn trả về lỗi mà chúng tôi không thể chuyển thành mã cụ thể hơn. Nội dung phản hồi bao gồm thông báo gốc. Các nguyên nhân thường gặp:

• Quá tải ở phía nhà cung cấp.
• Bị từ chối do kiểm duyệt nội dung (hãy thử prompt khác).
• Giới hạn theo khu vực / tình trạng khả dụng.

Chiến lược thử lại

Mẫu đơn giản và vững chắc nhất: dùng thời gian chờ tăng theo cấp số nhân, kèm độ lệch ngẫu nhiên, chỉ với 429 / 5xx.

import os
import random
import time

from openai import OpenAI, RateLimitError, APIError

client = OpenAI(api_key=os.environ["KUNAVO_API_KEY"], base_url="https://api.kunavo.com/v1")

def call_with_retry(call, max_attempts=5):
    for attempt in range(max_attempts):
        try:
            return call()
        except RateLimitError:
            if attempt + 1 == max_attempts: raise
            # 429: exponential backoff with jitter
            time.sleep(min(2 ** attempt, 30) + random.random())
        except APIError as e:
            if e.status_code and 500 <= e.status_code < 600 and attempt + 1 < max_attempts:
                time.sleep(min(2 ** attempt, 30) + random.random())
            else:
                raise

result = call_with_retry(lambda: client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "hi"}],
))

• Giới hạn thời gian chờ mỗi lần thử ở mức 30 giây và tổng số lần thử ở mức 5 lần.
• Đừng thử lại với lỗi 4xx (ngoại trừ 408 và 429). Làm vậy chỉ tốn thời gian.
• Việc tạo hình ảnh, video và nhạc không có tính lũy đẳng: mỗi lần thử lại là một lần tạo mới và sẽ bị tính phí nếu thành công. Với video, nhạc và hình ảnh, các endpoint gửi tác vụ bất đồng bộ (POST /v1/videos, POST /v1/audio/music/jobs và hai endpoint hình ảnh khi có "async": true hoặc webhook_url) chấp nhận header Idempotency-Key: gửi lại với cùng một khóa sẽ trả về tác vụ đầu tiên.
• Với các cuộc trò chuyện gây ra tác dụng phụ trong mã của bạn, hãy khử trùng lặp bằng khóa lũy đẳng ở tầng ứng dụng.

Gỡ lỗi từ trang tổng quan

Mọi lệnh gọi API — thành công hay thất bại — đều hiển thị tại /app/usage. Nhấp vào bất kỳ dòng nào để mở trang chi tiết đầy đủ về yêu cầu/phản hồi:

• Mã trạng thái HTTP trả về cho máy khách.
• Mã lỗi thượng nguồn (nếu có).
• Độ trễ, IP yêu cầu, user-agent.
• Lọc theo trạng thái giúp phát hiện các mẫu lỗi (ví dụ: mọi lỗi 422 trên một model cụ thể).

Báo cáo sự cố

Nếu liên tục gặp lỗi 5xx với một model đáng lẽ phải hoạt động, hãy gửi email đến support@kunavo.com kèm theo:

• Slug của model và nội dung yêu cầu mẫu (hãy xóa thông tin bí mật).
• Khoảng thời gian xảy ra lỗi.
• Lỗi code + message trong phản hồi.
• Nếu có thể, hãy gửi liên kết đến nhật ký sử dụng từ /app/usage/[id].

Thời gian phản hồi trong một ngày làm việc; nhanh hơn với các sự cố khẩn cấp ảnh hưởng đến doanh thu.

Tiếp theo nên xem gì

• Lỗi 402 / hạn mức bị ảnh hưởng thế nào bởi thanh toán
• Quản lý khóa API