Các lỗi mà agent có thể xử lý

Trang này mô tả lỗi API công khai có cấu trúc cho ứng dụng và tác tử lập trình. Nó không cấp quyền điều tra yêu cầu hoặc hỗ trợ của không gian làm việc. Hãy bắt đầu từ hướng dẫn xử lý sự cố.

Các lỗi TokenLab tương thích với OpenAI có thể bao gồm các gợi ý có cấu trúc dành cho agent hoặc ứng dụng. Hãy sử dụng các trường này khi chúng xuất hiện; đừng phân tích message (thông báo) ở dạng văn bản để quyết định phải làm gì.

Các API Anthropic Messages và Gemini giữ nguyên định dạng lỗi gốc của chúng, vì vậy các phần mở rộng trên trang này chỉ áp dụng cho các lỗi Chat Completions và Responses tương thích với OpenAI.

Các trường lỗi tùy chọnCopy Anchor Link

Tất cả các trường dưới đây xuất hiện bên trong đối tượng error và có thể không có sẵn.

Client của bạn vẫn nên xử lý mọi lỗi dựa trên HTTP status và code của chúng. Hãy coi các trường bổ sung này là ngữ cảnh hữu ích, không phải là các trường bắt buộc.

Model không xác địnhCopy Anchor Link

Một model bị viết sai chính tả hoặc không khả dụng sẽ trả về 400 model_not_found. Nếu did_you_mean xuất hiện, hãy hiển thị nó cho người dùng hoặc chỉ thử lại khi sản phẩm của bạn đã có quyền thay đổi model đã chọn.

{
  "error": {
    "message": "Model not found: please check the model name",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "did_you_mean": "gpt-5.6-terra",
    "suggestions": [
      {"id": "gpt-5.6-terra"},
      {"id": "gpt-5.6-luna"}
    ],
    "hint": "Did you mean 'gpt-5.6-terra'? Use GET https://api.tokenlab.sh/v1/models to list all available models."
  }
}

Số dư không đủCopy Anchor Link

Lỗi 402 insufficient_balance có thể bao gồm số dư hiện tại và số tiền ước tính cần thiết. Ứng dụng của bạn có thể cung cấp liên kết nạp tiền, gợi ý model rẻ hơn hoặc yêu cầu nhỏ hơn.

{
  "error": {
    "message": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-6, but balance is $0.1200.",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gpt-5.6-luna"},
      {"id": "deepseek-v3-2"}
    ],
    "hint": "Try a cheaper model, or top up at https://tokenlab.sh/dashboard/billing."
  }
}

Mô hình không khả dụngCopy Anchor Link

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

{
  "error": {
    "message": "This model is unavailable for the requested operation and Delivery tier.",
    "type": "all_channels_failed",
    "code": "all_channels_failed",
    "retryable": false,
    "hint": "Check the model's operation and Delivery availability with GET /v1/models. Repeating the same request will not resolve this."
  }
}

Giới hạn tốc độ (Rate limit)Copy Anchor Link

Đối với 429 rate_limit_exceeded, hãy đợi trong retry_after giây hoặc sử dụng header phản hồi tiêu chuẩn Retry-After.

{
  "error": {
    "message": "Rate limit: 1000 rpm exceeded",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Retry after 8s."
  }
}

Ngữ cảnh quá dàiCopy Anchor Link

Lỗi 400 context_length_exceeded không thể khắc phục bằng cách gửi lại cùng một yêu cầu. Hãy rút ngắn đầu vào hoặc để người dùng chọn một model có cửa sổ ngữ cảnh lớn hơn.

{
  "error": {
    "message": "This model's maximum context length is 128000 tokens...",
    "type": "invalid_request_error",
    "code": "context_length_exceeded",
    "retryable": false,
    "suggestions": [
      {"id": "gemini-2.5-pro"},
      {"id": "claude-sonnet-5"}
    ],
    "hint": "Reduce your input or switch to a model with a larger context window."
  }
}

Tìm định dạng API phù hợpCopy Anchor Link

Đọc tokenlab.accepted_request_formats từ GET /v1/models/{model} trước khi sử dụng API dành riêng cho model.

Định dạng được chấp nhận sẽ xác nhận endpoint. Các công cụ và trường riêng lẻ vẫn có thể thay đổi tùy theo model; hãy kiểm tra trang model trước khi phụ thuộc vào chúng.

Tìm model theo tác vụCopy Anchor Link

Models API có thể trả về danh sách rút gọn hiện tại cho các tác vụ không phải chat:

curl "https://api.tokenlab.sh/v1/models?recommended_for=image"

Các giá trị recommended_for hợp lệ là image, video, music, 3d, tts, stt, embedding, rerank và translation. Hãy gửi ID model đã chọn một cách rõ ràng trong yêu cầu tạo. TokenLab không tự động thay thế nó bằng một model khác.

Tổng quan dành cho máy đọcCopy Anchor Link

Các agent có thể đọc tổng quan API cô đọng tại:

GET https://api.tokenlab.sh/llms.txt

Nó bao gồm yêu cầu đầu tiên, các endpoint phổ biến, bộ lọc model và hướng dẫn xử lý lỗi.

Xử lý lỗi mà không gửi lại yêu cầuCopy Anchor Link

Ví dụ chỉ gửi một yêu cầu, giữ nguyên mô hình đã chọn và hiển thị thông tin lỗi có cấu trúc. Tính năng thử lại tự động của SDK bị tắt. Để người dùng chủ động chọn mô hình được gợi ý; không tự gửi lại yêu cầu tạo nội dung đã được nhận hoặc hết thời gian chờ.

import os
from openai import OpenAI, APIStatusError

with OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
) as client:
    try:
        response = client.chat.completions.create(
            model="gpt-5.6-terra",
            messages=[{"role": "user", "content": "Reply only with OK."}],
        )
        print(response.choices[0].message.content)
    except APIStatusError as exc:
        body = exc.body if isinstance(exc.body, dict) else {}
        error = body.get("error", body)
        if not isinstance(error, dict):
            error = {}
        print({
            "status": exc.status_code,
            "request_id": exc.request_id,
            "code": error.get("code"),
            "hint": error.get("hint"),
            "suggested_model": error.get("did_you_mean"),
            "retry_after": exc.response.headers.get("Retry-After") or error.get("retry_after"),
        })
        raise