Panduan inti

Error yang dapat ditangani oleh agen

Gunakan kode error, waktu tunggu percobaan ulang, dan saran model tanpa harus memproses teks

Halaman ini menjelaskan error API publik yang dapat dibaca mesin untuk aplikasi dan agen pengodean. Halaman ini tidak memberikan akses ke investigasi permintaan ruang kerja atau dukungan. Untuk permintaan di ruang kerja Anda, mulailah dengan pemecahan masalah permintaan.

Error TokenLab yang kompatibel dengan OpenAI dapat menyertakan petunjuk terstruktur untuk agen atau aplikasi. Gunakan kolom-kolom ini jika tersedia; jangan memproses message yang dapat dibaca manusia untuk memutuskan apa yang harus dilakukan.

API Anthropic Messages dan Gemini tetap menggunakan format error aslinya, sehingga ekstensi pada halaman ini hanya berlaku untuk error Chat Completions dan Responses yang kompatibel dengan OpenAI.

Kolom error opsional

Semua kolom di bawah ini muncul di dalam objek error dan mungkin tidak ada.

KolomTipeKegunaan
did_you_meanstringPengganti untuk model yang sudah tidak digunakan, atau ID model terdekat yang tersedia
suggestionsarrayModel yang mungkin sesuai dengan permintaan
hintstringPenjelasan singkat atau tindakan yang disarankan
retryablebooleanApakah permintaan yang sama mungkin berhasil di kemudian waktu
retry_afternumberDetik untuk menunggu sebelum mencoba lagi
balance_usdnumberSaldo saat ini dalam USD
estimated_cost_usdnumberEstimasi biaya dari permintaan yang ditolak
top_up_urlstringTautan halaman penagihan, pada beberapa error insufficient_balance
min_top_up_usdnumberTop-up minimum dalam USD, pada beberapa error insufficient_balance

Klien Anda harus tetap menangani setiap error berdasarkan status HTTP dan code-nya. Anggap kolom tambahan ini sebagai konteks yang berguna, bukan kolom wajib.

Model tidak diketahui

Model yang salah ketik atau tidak tersedia akan mengembalikan 400 model_not_found. Jika did_you_mean tersedia, tampilkan kepada pengguna atau coba lagi hanya jika produk Anda sudah memiliki izin untuk mengubah model yang dipilih.

{
  "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 /v1/models to list all available models."
  }
}

Saldo tidak mencukupi

402 insufficient_balance dapat menyertakan saldo saat ini dan estimasi jumlah yang diperlukan, atau tautan top-up dan jumlah top-up minimum. Aplikasi Anda dapat menawarkan tautan top-up, model yang lebih murah, atau permintaan yang lebih kecil.

{
  "error": {
    "message": "Insufficient balance: this request needs about $0.35 for claude-sonnet-4-6, and your balance is $0.12. Add at least $5 to continue: https://tokenlab.sh/dashboard/billing · Why: https://tokenlab.sh/docs/en/quickstart#why-402 After you top up, your current API key works immediately, no new key needed.",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "retryable": false,
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gpt-5.6-luna"},
      {"id": "deepseek-v4.1-flash"}
    ],
    "hint": "Insufficient balance: need ~$0.350000 for claude-sonnet-4-6, but balance is $0.120000. Try a cheaper model, or top up at https://tokenlab.sh/dashboard/billing."
  }
}

Model tidak tersedia

503 all_channels_failed atau 503 delivery_tier_unavailable tidak selalu berarti gangguan sementara. Jika operasi yang diminta tidak memiliki pasokan di tingkat Delivery yang dipilih, retryable akan bernilai false dan retry_after akan dihilangkan. Jangan ulangi permintaan yang sama. Periksa ketersediaan operasi dan Delivery dengan GET /v1/models sebelum memilih model lain. Nama yang mirip tidak menjamin ketersediaan; alternatif yang belum diverifikasi akan dihilangkan.

{
  "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."
  }
}

Batas kecepatan (Rate limit)

Untuk 429 rate_limit_exceeded, tunggu selama retry_after detik atau gunakan header respons standar Retry-After.

{
  "error": {
    "message": "Rate limit exceeded (1000/min for user role). Please retry later.",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Rate limited. Retry after 8s. Current limit: 1000/min for user role."
  }
}

Konteks terlalu panjang

400 context_length_exceeded tidak dapat diperbaiki dengan mengirimkan permintaan yang sama kembali. Persingkat input atau biarkan pengguna memilih model dengan jendela konteks yang lebih besar.

{
  "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."
  }
}

Menemukan format API yang tepat

Baca tokenlab.accepted_request_formats dari GET /v1/models/{model} sebelum menggunakan API khusus model.

NilaiEndpoint
openai_chat_completions/v1/chat/completions
openai_responses/v1/responses
anthropic_messages/v1/messages
gemini_generate_content/v1beta/models/{model}:generateContent

Format yang diterima mengonfirmasi endpoint. Alat dan kolom individual masih dapat bervariasi tergantung model; periksa halaman model sebelum mengandalkannya.

Menemukan model berdasarkan tugas

API Models dapat mengembalikan daftar singkat saat ini untuk tugas non-chat:

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

Nilai recommended_for yang valid adalah image, video, music, 3d, tts, stt, embedding, rerank, translation, dan decision. Kirim ID model yang dipilih secara eksplisit dalam permintaan pembuatan. TokenLab tidak akan menggantinya secara diam-diam dengan model yang berbeda.

Ringkasan yang dapat dibaca mesin

Agen dapat membaca ringkasan API yang ringkas di:

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

Ringkasan ini mencakup permintaan pertama, endpoint umum, filter model, dan panduan penanganan error.

Menangani error tanpa memutar ulang permintaan

Contoh ini melakukan satu permintaan, mempertahankan model yang dipilih, dan melaporkan informasi pemulihan terstruktur. Percobaan ulang SDK dinonaktifkan agar aplikasi Anda dapat memutuskan apakah percobaan ulang aman dilakukan. Sajikan saran model untuk pilihan eksplisit; jangan memutar ulang pembuatan yang diterima atau yang telah habis waktu (timed-out) secara otomatis. Untuk mencoba ulang permintaan yang habis waktu dengan aman, kirimkan dengan Idempotency-Key, seperti yang ditunjukkan dalam Coba ulang dengan aman menggunakan kunci idempotensi.

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

Di halaman ini