TokenLab

Hướng dẫn cốt lõi

Xử lý lỗi API

Đọc mã lỗi, chỉ thử lại khi cần thiết và lưu giữ Request ID

Xử lý lỗi dựa trên trạng thái HTTP và code. Nội dung message được viết cho người dùng và có thể thay đổi mà không cần thông báo trước.

Chat Completions và Responses sử dụng đối tượng error theo phong cách OpenAI. Anthropic Messages và Gemini giữ các định dạng lỗi riêng của chúng, vì vậy đừng sử dụng một trình phân tích cú pháp duy nhất cho mọi API của TokenLab.

{
  "error": {
    "message": "Human-readable description",
    "type": "error_type",
    "code": "error_code",
    "param": "parameter_name",
    "retryable": true,
    "retry_after": 30
  }
}

Chỉ message và type là luôn xuất hiện trong các lỗi tương thích với OpenAI do TokenLab tạo ra. Các trường khác sẽ xuất hiện khi chúng liên quan.

Mã trạng thái

Trạng tháiÝ nghĩaHành động thông thường
400Một trường, ID mô hình hoặc đầu vào không hợp lệSửa yêu cầu; không gửi lại nếu chưa thay đổi
401Thiếu API key, không hợp lệ, hết hạn hoặc đã bị thu hồiThay thế bằng key mới
402Số dư hoặc giới hạn của API key quá thấpNạp thêm tiền, tăng giới hạn hoặc giảm yêu cầu
403Key này không thể sử dụng tài nguyên hoặc mô hình, hoặc tài khoản bị hạn chếThay đổi quyền của key hoặc mô hình, hoặc liên hệ bộ phận hỗ trợ
404Tài nguyên không tồn tại hoặc không còn khả dụngKiểm tra ID và API key đã tạo ra nó
409Idempotency-Key đã được sử dụng: với nội dung yêu cầu khác (idempotency_conflict), hoặc cho một yêu cầu mà TokenLab không thể trả về kết quả (idempotency_replay_unavailable, idempotent_response_not_replayable). TokenLab đã không thực hiện lại yêu cầuSử dụng key mới cho yêu cầu mới. Để quyết định xem có nên thử lại với cùng một key hay không, hãy xem Thử lại an toàn với idempotency key
413Yêu cầu hoặc tệp tải lên quá lớnGiảm đầu vào xuống giới hạn của mô hình hoặc endpoint đã ghi trong tài liệu
429Đã đạt giới hạn yêu cầuChờ theo thời gian Retry-After
500–504Dịch vụ không khả dụng hoặc lỗi mạngChỉ thử lại khi retryable là true; tuân thủ retry_after và giới hạn số lần thử

Mã lỗi phổ biến

MãÝ nghĩaCần thay đổi gì
invalid_api_keyAPI key bị thiếu, không hợp lệ, không hoạt động hoặc đã bị thu hồiKiểm tra tiêu đề Authorization và giá trị key
expired_api_keyKey đã hết hạnTạo hoặc chọn một key đang hoạt động
insufficient_balanceSố dư tài khoản không đủ để thực hiện yêu cầuNạp thêm tiền, giảm yêu cầu hoặc chọn mô hình có giá thấp hơn
quota_exceededAPI key đã đạt giới hạn riêngTăng giới hạn của key đó hoặc sử dụng key được ủy quyền khác
model_not_allowedKey không thể sử dụng mô hình được yêu cầuCập nhật danh sách mô hình của key hoặc chọn mô hình được cho phép
user_suspended, account_restrictedHTTP 403. Tài khoản không thể sử dụng APILiên hệ bộ phận hỗ trợ kèm theo Request ID
invalid_delivery_policyHTTP 400. Tiêu đề X-TokenLab-Delivery-Policy không phải là auto, verified hoặc officialGửi một trong ba giá trị này, hoặc xóa tiêu đề
model_not_foundID mô hình không xác định hoặc không khả dụngĐọc /v1/models và sử dụng ID mô hình hiện tại
context_length_exceededĐầu vào dài hơn mức mô hình chấp nhậnXóa bớt lịch sử hoặc chọn mô hình có cửa sổ ngữ cảnh lớn hơn
missing_required_parameterThiếu trường bắt buộc. param sẽ nêu tên trường đó, ví dụ model trong các yêu cầu âm thanh và hình ảnh, vốn không có mô hình mặc địnhGửi trường mà param đã nêu
invalid_valueMột trường có giá trị mà mô hình không chấp nhận, ví dụ giá trị reasoning_effort. Thông báo sẽ liệt kê các giá trị được chấp nhậnSử dụng một trong các giá trị được liệt kê
invalid_response_format_typeHTTP 400. response_format là một object nhưng không có type dùng được, hoặc có type mà endpoint này không chấp nhận. param là response_formatĐặt response_format.type thành text, json_object hoặc json_schema; với json_schema, gửi thêm json_schema.name và json_schema.schema
invalid_image_urlTokenLab không thể sử dụng URL hình ảnh: đây không phải là URL HTTP(S) hợp lệ hoặc URI dữ liệu hình ảnh, hoặc máy chủ hình ảnh không trả về hình ảnh. param sẽ nêu tên trườngGửi URL hình ảnh HTTPS công khai hoặc URI dữ liệu được hỗ trợ
unsupported_model_capabilityKhông có lộ trình nào của cấp Delivery đã chọn hỗ trợ tham số yêu cầu, chẳng hạn như thao tác, resolution, aspect_ratio, duration, trường phương tiện đầu vào, web_search_options hoặc max_tokens. Thông báo sẽ nêu tên từng tham số không khớp và, khi mô hình công bố chúng, các giá trị được hỗ trợXóa hoặc thay đổi tham số, hoặc chọn cấp Delivery hoặc mô hình khác; không lặp lại yêu cầu mà không thay đổi
unpriceable_selectionYêu cầu video bỏ qua một bộ chọn mà giá của nó phụ thuộc vào đó, vì vậy TokenLab không thể định giá. param sẽ nêu tên bộ chọnThiết lập trường mà param đã nêu
model_pricing_unavailableHTTP 503. Yêu cầu hợp lệ, nhưng TokenLab không thể định giá sự kết hợp giữa mô hình và thao tác này trên các lộ trình mà yêu cầu có thể sử dụng. Yêu cầu không bị tính phí và retryable là falseKhông lặp lại yêu cầu mà không thay đổi; chọn mô hình hoặc thao tác khác, hoặc liên hệ bộ phận hỗ trợ kèm theo Request ID
idempotency_conflictHTTP 409. Idempotency-Key thuộc về một yêu cầu khác. TokenLab đã không thực hiện yêu cầu nàyGửi yêu cầu mới với key mới
idempotency_replay_unavailableHTTP 409. Idempotency-Key đã được sử dụng và TokenLab không có kết quả để trả về cho nó. TokenLab đã không thực hiện lại yêu cầu nàyNếu yêu cầu đầu tiên vẫn có thể đang chạy, hãy đợi và thử lại với cùng một key. Nếu không, hãy gửi key mới. Xem Thử lại an toàn với idempotency key
idempotent_response_not_replayableHTTP 409. Idempotency-Key thuộc về một yêu cầu tạo đã hoàn thành tác vụ, và TokenLab không thể trả về phản hồi tạo ban đầu. Cấp cao nhất của nội dung phản hồi bao gồm task_id, bên cạnh error. TokenLab đã không thực hiện lại yêu cầu nàyKhông lặp lại yêu cầu với key này. Chỉ gửi key mới nếu bạn muốn một tác vụ mới
rate_limit_exceededQuá nhiều yêu cầu được gửi trong cửa sổ hiện tạiChờ theo thời gian Retry-After
all_channels_failedMô hình đã chọn không thể phục vụ yêu cầu nàyChỉ thử lại khi retryable là true; tuân thủ retry_after và giới hạn số lần thử
timeout_errorYêu cầu không hoàn thành kịp thờiChỉ thử lại khi thao tác an toàn để lặp lại

Lỗi 503 all_channels_failed hoặc 503 delivery_tier_unavailable không phải lúc nào cũng có nghĩa là sự cố tạm thời. Nếu thao tác được yêu cầu không có nguồn cung trong cấp Delivery đã chọn, retryable sẽ là false và retry_after bị bỏ qua. Không lặp lại cùng một yêu cầu. Kiểm tra thao tác và tính khả dụng của Delivery với GET /v1/models trước khi chọn mô hình khác. Các tên tương tự không chứng minh được tính khả dụng; các lựa chọn thay thế chưa được xác minh sẽ bị bỏ qua.

Một số lỗi tương thích với OpenAI bao gồm các trường tùy chọn did_you_mean, suggestions, alternatives, hint, retryable hoặc retry_after. Xem Các lỗi mà agent có thể xử lý.

Khi một yêu cầu chạy trên lộ trình Official và dịch vụ thượng nguồn từ chối chính yêu cầu đó, chẳng hạn như đầu vào không được chấp nhận hoặc quyết định về chính sách nội dung, lỗi cũng sẽ mang theo upstream: message của thượng nguồn như đã báo cáo, cộng với code và source (tên dịch vụ thượng nguồn) khi được biết. Các lỗi của Anthropic Messages và Gemini mang cùng đối tượng đó bên trong error của riêng chúng. Hãy tiếp tục phân nhánh dựa trên code và type; các giá trị upstream.code được xác định bởi dịch vụ thượng nguồn và có thể thay đổi.

Quyết định thử lại

LỗiLặp lại cùng một yêu cầu?
400, 401, 402, 403, 404, 413Không. Thay đổi yêu cầu, thông tin xác thực, số dư, quyền hoặc đầu vào.
429Có, sau khoảng thời gian trễ do máy chủ cung cấp.
500–504Chỉ thử lại khi retryable là true; tuân thủ retry_after và giới hạn số lần thử
Kết nối bị đóng trước khi có phản hồiCó, khi yêu cầu được liệt kê trong Thử lại an toàn với idempotency key và có Idempotency-Key: gửi lại với cùng key và nội dung. Nếu không, trước tiên hãy kiểm tra xem tác vụ hoặc tác dụng phụ đã tồn tại chưa.
Luồng bị gián đoạn sau khi đầu ra đã đếnĐừng coi đó là một phản hồi hoàn chỉnh. Việc lặp lại có thể tạo ra đầu ra khác hoặc bị tính phí lần thứ hai.

Đối với việc tạo hình ảnh, video, âm nhạc, 3D và Worlds, hãy lưu ID tác vụ ngay khi nó được trả về. Nếu yêu cầu tạo bị hết thời gian chờ, hãy gửi lại với cùng Idempotency-Key và nội dung để nhận tác vụ ban đầu. Nếu không có key, hãy kiểm tra bản ghi tác vụ trước khi gửi yêu cầu tạo khác.

Thử lại an toàn với idempotency key

Việc hết thời gian chờ hoặc kết nối bị đóng không cho bạn biết liệu TokenLab đã thực hiện yêu cầu hay chưa. Thêm tiêu đề Idempotency-Key vào các yêu cầu được liệt kê dưới đây. Khi đó, việc thử lại cùng một yêu cầu sẽ không thể chạy hoặc tính phí lần thứ hai.

  • Sử dụng một giá trị duy nhất mới cho mỗi thao tác, ví dụ như UUID. Một key có thể có tối đa 255 ký tự. TokenLab bỏ qua key dài hơn, và yêu cầu đó sẽ không có bảo vệ idempotency: việc thử lại sẽ chạy và bị tính phí lần nữa. POST /v1/messages/batches thì khác: nó từ chối key dài hơn 256 ký tự với mã 400.
  • Lưu key cùng với bản ghi công việc của riêng bạn trước khi gửi yêu cầu.
  • Khi thử lại, hãy gửi cùng API key, cùng Idempotency-Key và cùng nội dung.
  • Sau bất kỳ phản hồi nào khác ngoài 409 với idempotency_replay_unavailable, đừng sử dụng lại key đó. Hãy gửi bất kỳ lần thử mới nào với một key mới.
  • Tắt tính năng thử lại của SDK (max_retries=0), để mã của bạn quyết định khi nào nên sử dụng lại key.

Nếu không có tiêu đề, mỗi lần thử lại là một yêu cầu mới.

Các yêu cầu tạo tác vụ

Các yêu cầu tạo này chấp nhận Idempotency-Key:

  • POST /v1/videos/generations, POST /v1/music/generations, POST /v1/3d/generations và POST /v1/worlds/generations
  • POST /v1/images/generations và POST /v1/images/edits khi chúng trả về một tác vụ
  • POST /v1/responses với "background": true
  • POST /v1/messages/batches

Nếu yêu cầu tạo bị hết thời gian chờ, hãy gửi lại mà không thay đổi. TokenLab trả về kết quả của yêu cầu tạo ban đầu và không tạo, gửi hoặc tính phí tác vụ thứ hai. Thông thường kết quả là tác vụ ban đầu với cùng id (đối với Responses, là đối tượng phản hồi ban đầu), và bạn tiếp tục thăm dò nó. Đối với các tác vụ video, âm nhạc, 3D, Worlds và hình ảnh, kết quả cũng có thể là lỗi ban đầu khi yêu cầu tạo đầu tiên thất bại. Nếu tác vụ đó đã hoàn thành và TokenLab không có phản hồi tạo được lưu trữ, lần thử lại sẽ trả về 409 với mã idempotent_response_not_replayable, và cấp cao nhất của nội dung phản hồi bao gồm task_id.

Nếu bạn gửi nội dung khác với key mà TokenLab đã chấp nhận, TokenLab sẽ từ chối yêu cầu và không tạo tác vụ. Các yêu cầu tạo video, âm nhạc, 3D và Worlds trả về 409 với mã idempotency_conflict. Message Batches trả về 409 với loại lỗi conflict_error. Đối với các tác vụ hình ảnh và yêu cầu Responses với background: true, mã trạng thái và mã lỗi cho trường hợp này không được đảm bảo. Đừng thử lại yêu cầu với cùng một key.

Chat Completions, Responses và Messages

POST /v1/chat/completions, POST /v1/responses không có background và POST /v1/messages chỉ chạy yêu cầu với một key nhất định một lần. Việc thử lại với cùng key sẽ nhận được một trong các kết quả sau:

Tình huốngKết quả
Yêu cầu đầu tiên vẫn đang chạy409 với mã idempotency_replay_unavailable
Yêu cầu đầu tiên đã hoàn thành sau khi client của bạn ngắt kết nối. Yêu cầu không được truyền phát (streamed), kết quả từ 1 MB trở xuống và bạn thử lại với cùng nội dung trong vòng 24 giờ200 với nội dung phản hồi ban đầu và tiêu đề Idempotent-Replayed: true. TokenLab không chạy hoặc tính phí yêu cầu lần nữa
Key đã được sử dụng theo bất kỳ cách nào khác, ví dụ: bạn đã nhận được kết quả, yêu cầu đã được truyền phát, kết quả lớn hơn 1 MB hoặc đã quá 24 giờ409 với mã idempotency_replay_unavailable
Nội dung khác với yêu cầu đầu tiên409, thường với mã idempotency_conflict. Một số yêu cầu trả về idempotency_replay_unavailable

Mã 409 với bất kỳ mã nào trong hai mã trên có nghĩa là TokenLab đã không thực hiện lại yêu cầu. Một yêu cầu được truyền phát với một key không thể chạy hai lần, nhưng TokenLab không thể gửi lại đầu ra của nó.

Ví dụ này thử lại yêu cầu Chat Completions bị hết thời gian chờ với cùng một key cho đến khi nhận được kết quả:

import os
import time
import uuid
import openai
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=120.0,
    max_retries=0,
)

def create_once(messages, model="gpt-5.6-terra", waits=(0, 5, 15, 45)):
    key = str(uuid.uuid4())  # Lưu key này cùng với bản ghi công việc của bạn.
    for wait in waits:
        time.sleep(wait)
        try:
            return client.chat.completions.create(
                model=model,
                messages=messages,
                extra_headers={"Idempotency-Key": key},
            )
        except (openai.APITimeoutError, openai.APIConnectionError):
            continue  # Không có phản hồi: thử lại với cùng key và nội dung.
        except openai.ConflictError as exc:
            if exc.code != "idempotency_replay_unavailable":
                raise
            # Lần thử đầu tiên có thể vẫn đang chạy. Lần thử lại sau sẽ trả về kết quả của nó.
    raise RuntimeError(f"No result for Idempotency-Key {key}")

Nếu lần thử cuối cùng vẫn trả về idempotency_replay_unavailable, TokenLab không thể trả về kết quả đó. Chỉ gửi yêu cầu với key mới nếu việc chạy lần thứ hai và tính phí lần thứ hai là chấp nhận được.

Lưu giữ Request ID

Các tiêu đề phản hồi bao gồm Request ID để theo dõi. Hãy lưu nó cùng với endpoint, mô hình, thời gian và ID người dùng hoặc ID công việc của riêng bạn. Đối với công việc không đồng bộ (async), hãy lưu cả task_id và billing_transaction_id khi có.

Khi liên hệ bộ phận hỗ trợ, hãy bao gồm các ID đó và một ví dụ đã được biên tập lại. Không bao giờ gửi API key, token quản lý, phương tiện riêng tư, URL đã ký hoặc các prompt riêng tư hoàn chỉnh.

Từ một yêu cầu đến quá trình điều tra và hỗ trợ

Trên trang này