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.
| Kolom | Tipe | Kegunaan |
|---|---|---|
did_you_mean | string | Pengganti untuk model yang sudah tidak digunakan, atau ID model terdekat yang tersedia |
suggestions | array | Model yang mungkin sesuai dengan permintaan |
hint | string | Penjelasan singkat atau tindakan yang disarankan |
retryable | boolean | Apakah permintaan yang sama mungkin berhasil di kemudian waktu |
retry_after | number | Detik untuk menunggu sebelum mencoba lagi |
balance_usd | number | Saldo saat ini dalam USD |
estimated_cost_usd | number | Estimasi biaya dari permintaan yang ditolak |
top_up_url | string | Tautan halaman penagihan, pada beberapa error insufficient_balance |
min_top_up_usd | number | Top-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.
| Nilai | Endpoint |
|---|---|
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.txtRingkasan 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