Panduan inti
Menangani error API
Baca kode error, lakukan retry hanya jika berguna, dan simpan Request ID
Tangani error berdasarkan status HTTP dan code. message ditulis untuk manusia dan dapat berubah sewaktu-waktu tanpa pemberitahuan.
Chat Completions dan Responses menggunakan objek error bergaya OpenAI. Anthropic Messages dan Gemini memiliki format error tersendiri, jadi jangan gunakan satu parser untuk setiap API TokenLab.
{
"error": {
"message": "Human-readable description",
"type": "error_type",
"code": "error_code",
"param": "parameter_name",
"retryable": true,
"retry_after": 30
}
}Hanya message dan type yang selalu ada dalam error yang kompatibel dengan OpenAI yang dibuat oleh TokenLab. Bidang lain akan muncul jika relevan.
Kode status
| Status | Arti | Tindakan umum |
|---|---|---|
400 | Bidang, ID model, atau input tidak valid | Perbaiki permintaan; jangan ulangi tanpa perubahan |
401 | API key hilang, tidak valid, kedaluwarsa, atau dicabut | Ganti key |
402 | Saldo atau batas API-key terlalu rendah | Isi ulang, naikkan batas, atau kurangi permintaan |
403 | Key ini tidak dapat menggunakan sumber daya atau model tersebut, atau akun dibatasi | Ubah izin key atau model, atau hubungi dukungan |
404 | Sumber daya tidak ada atau tidak lagi tersedia | Periksa ID dan API key yang membuatnya |
409 | Idempotency-Key sudah digunakan: dengan body permintaan yang berbeda (idempotency_conflict), atau untuk permintaan yang hasilnya tidak dapat dikembalikan oleh TokenLab (idempotency_replay_unavailable, idempotent_response_not_replayable). TokenLab tidak menjalankan kembali permintaan tersebut | Gunakan key baru untuk permintaan baru. Untuk memutuskan apakah akan melakukan retry dengan key yang sama, lihat Retry dengan aman menggunakan idempotency key |
413 | Permintaan atau file yang diunggah terlalu besar | Kurangi input sesuai batas model atau endpoint yang didokumentasikan |
429 | Batas permintaan tercapai | Tunggu hingga Retry-After |
500–504 | Layanan tidak tersedia atau kegagalan jaringan | Lakukan retry hanya jika retryable bernilai true; patuhi retry_after dan batasi percobaan |
Kode error umum
| Kode | Apa artinya | Apa yang harus diubah |
|---|---|---|
invalid_api_key | API key hilang, tidak valid, tidak aktif, atau dicabut | Periksa header Authorization dan nilai key |
expired_api_key | Key telah kedaluwarsa | Buat atau pilih key yang aktif |
insufficient_balance | Saldo akun tidak mencukupi untuk permintaan tersebut | Tambahkan dana, kurangi permintaan, atau pilih model dengan harga lebih rendah |
quota_exceeded | API key mencapai batasnya sendiri | Tingkatkan batas key tersebut atau gunakan key resmi lainnya |
model_not_allowed | Key tidak dapat menggunakan model yang diminta | Perbarui daftar model key atau pilih model yang diizinkan |
user_suspended, account_restricted | HTTP 403. Akun tidak dapat menggunakan API | Hubungi dukungan dengan menyertakan Request ID |
invalid_delivery_policy | HTTP 400. Header X-TokenLab-Delivery-Policy bukan auto, verified, atau official | Kirim salah satu dari tiga nilai tersebut, atau hapus header |
model_not_found | ID model tidak diketahui atau tidak tersedia | Baca /v1/models dan gunakan ID model yang saat ini berlaku |
context_length_exceeded | Input lebih panjang dari yang diterima model | Hapus riwayat atau pilih model dengan jendela konteks yang lebih besar |
missing_required_parameter | Bidang wajib diisi hilang. param menyebutkan namanya, contohnya model pada permintaan audio dan gambar, yang tidak memiliki model default | Kirim bidang yang disebutkan oleh param |
invalid_value | Bidang memiliki nilai yang tidak diterima model, contohnya nilai reasoning_effort. Pesan mencantumkan nilai yang diterima | Gunakan salah satu nilai yang tercantum |
invalid_response_format_type | HTTP 400. response_format adalah objek tanpa type yang dapat digunakan, atau dengan type yang tidak diterima endpoint ini. param adalah response_format | Setel response_format.type ke text, json_object, atau json_schema; dengan json_schema, kirim juga json_schema.name dan json_schema.schema |
invalid_image_url | TokenLab tidak dapat menggunakan URL gambar: bukan URL HTTP(S) atau URI data gambar yang valid, atau host gambar tidak mengembalikan gambar. param menyebutkan bidangnya | Kirim URL gambar HTTPS publik atau URI data yang didukung |
unsupported_model_capability | Tidak ada rute dari Delivery tier yang dipilih yang mendukung parameter permintaan, seperti operasi, resolution, aspect_ratio, duration, bidang media input, web_search_options, atau max_tokens. Pesan menyebutkan setiap parameter yang tidak cocok dan, jika model mempublikasikannya, nilai yang didukung | Hapus atau ubah parameter, atau pilih Delivery tier atau model lain; jangan ulangi permintaan tanpa perubahan |
unpriceable_selection | Permintaan video melewatkan pemilih yang menjadi dasar harganya, sehingga TokenLab tidak dapat menentukan harganya. param menyebutkan pemilihnya | Atur bidang yang disebutkan oleh param |
model_pricing_unavailable | HTTP 503. Permintaan valid, tetapi TokenLab tidak dapat menentukan harga kombinasi model dan operasi ini pada rute yang dapat digunakan permintaan. Permintaan tidak dikenakan biaya, dan retryable bernilai false | Jangan ulangi permintaan tanpa perubahan; pilih model atau operasi lain, atau hubungi dukungan dengan menyertakan Request ID |
idempotency_conflict | HTTP 409. Idempotency-Key milik permintaan yang berbeda. TokenLab tidak menjalankan permintaan ini | Kirim permintaan baru dengan key baru |
idempotency_replay_unavailable | HTTP 409. Idempotency-Key sudah digunakan, dan TokenLab tidak memiliki hasil untuk dikembalikan. TokenLab tidak menjalankan kembali permintaan ini | Jika permintaan pertama mungkin masih berjalan, tunggu dan lakukan retry dengan key yang sama. Jika tidak, kirim key baru. Lihat Retry dengan aman menggunakan idempotency key |
idempotent_response_not_replayable | HTTP 409. Idempotency-Key milik permintaan pembuatan yang tugasnya sudah selesai, dan TokenLab tidak dapat mengembalikan respons pembuatan asli. Level teratas dari body respons menyertakan task_id, di samping error. TokenLab tidak menjalankan kembali permintaan ini | Jangan ulangi permintaan dengan key ini. Kirim key baru hanya jika Anda menginginkan tugas baru |
rate_limit_exceeded | Terlalu banyak permintaan dikirim dalam jendela waktu saat ini | Tunggu hingga Retry-After |
all_channels_failed | Model yang dipilih tidak dapat melayani permintaan ini | Lakukan retry hanya jika retryable bernilai true; patuhi retry_after dan batasi percobaan |
timeout_error | Permintaan tidak selesai tepat waktu | Lakukan retry hanya jika operasi aman untuk diulangi |
503 all_channels_failed atau 503 delivery_tier_unavailable tidak selalu berarti gangguan sementara. Jika operasi yang diminta tidak memiliki pasokan di Delivery tier yang dipilih, retryable bernilai false dan retry_after 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 tidak terverifikasi dihilangkan.
Beberapa error yang kompatibel dengan OpenAI menyertakan bidang opsional did_you_mean, suggestions, alternatives, hint, retryable, atau retry_after. Lihat Error yang dapat ditindaklanjuti oleh agen.
Ketika permintaan berjalan pada rute Official dan layanan upstream menolak permintaan itu sendiri, seperti input yang tidak diterima atau keputusan kebijakan konten, error tersebut juga membawa upstream: message upstream sebagaimana dilaporkan, ditambah code dan source (nama layanan upstream) jika diketahui. Error Anthropic Messages dan Gemini membawa objek yang sama di dalam error mereka sendiri. Terus lakukan percabangan pada code dan type; nilai upstream.code ditentukan oleh layanan upstream dan dapat berubah.
Keputusan retry
| Error | Ulangi permintaan yang sama? |
|---|---|
400, 401, 402, 403, 404, 413 | Tidak. Ubah permintaan, kredensial, saldo, izin, atau input. |
429 | Ya, setelah penundaan yang diberikan server. |
500–504 | Lakukan retry hanya jika retryable bernilai true; patuhi retry_after dan batasi percobaan |
| Koneksi terputus sebelum ada respons | Ya, jika permintaan tercantum dalam Retry dengan aman menggunakan idempotency key dan memiliki Idempotency-Key: kirim kembali dengan key dan body yang sama. Jika tidak, periksa terlebih dahulu apakah tugas atau efek samping sudah ada. |
| Stream terputus setelah output tiba | Jangan sebut sebagai respons lengkap. Mengulangi dapat menghasilkan output yang berbeda atau biaya kedua. |
Untuk pembuatan gambar, video, musik, 3D, dan Worlds, simpan ID tugas segera setelah dikembalikan. Jika permintaan pembuatan mengalami timeout, kirim kembali dengan Idempotency-Key dan body yang sama untuk mendapatkan tugas asli. Tanpa key, periksa catatan tugas sebelum mengirim permintaan pembuatan lainnya.
Retry dengan aman menggunakan idempotency key
Timeout atau koneksi yang terputus tidak memberi tahu Anda apakah TokenLab menjalankan permintaan tersebut. Tambahkan header Idempotency-Key ke permintaan yang tercantum di bawah. Dengan begitu, retry dari permintaan yang sama tidak dapat menjalankan atau menagihnya untuk kedua kalinya.
- Gunakan nilai unik baru untuk setiap operasi, misalnya UUID. Key dapat memiliki panjang hingga 255 karakter. TokenLab mengabaikan key yang lebih panjang, dan permintaan tersebut kemudian tidak memiliki perlindungan idempotensi: retry akan berjalan dan ditagih kembali.
POST /v1/messages/batchesberbeda: ia menolak key yang lebih panjang dari 256 karakter dengan400. - Simpan key dengan catatan pekerjaan Anda sendiri sebelum mengirim permintaan.
- Saat melakukan retry, kirim API key yang sama,
Idempotency-Keyyang sama, dan body yang sama. - Setelah respons apa pun selain
409denganidempotency_replay_unavailable, jangan gunakan key tersebut lagi. Kirim percobaan baru dengan key baru. - Matikan retry SDK (
max_retries=0), agar kode Anda yang memutuskan kapan harus menggunakan kembali key.
Tanpa header, setiap retry adalah permintaan baru.
Permintaan yang membuat tugas
Permintaan pembuatan ini menerima Idempotency-Key:
POST /v1/videos/generations,POST /v1/music/generations,POST /v1/3d/generations, danPOST /v1/worlds/generationsPOST /v1/images/generationsdanPOST /v1/images/editssaat mengembalikan tugasPOST /v1/responsesdengan"background": truePOST /v1/messages/batches
Jika permintaan pembuatan mengalami timeout, kirim kembali tanpa perubahan. TokenLab mengembalikan hasil dari permintaan pembuatan asli dan tidak membuat, mengirim, atau menagih tugas kedua. Biasanya hasilnya adalah tugas asli dengan id yang sama (untuk Responses, objek respons asli), dan Anda terus melakukan polling. Untuk tugas video, musik, 3D, Worlds, dan gambar, hasilnya juga bisa berupa error asli saat permintaan pembuatan pertama gagal. Jika tugas tersebut sudah selesai dan TokenLab tidak memiliki respons pembuatan yang tersimpan, retry akan mengembalikan 409 dengan kode idempotent_response_not_replayable, dan level teratas dari body respons menyertakan task_id.
Jika Anda mengirim body yang berbeda dengan key yang sudah diterima TokenLab, TokenLab menolak permintaan dan tidak membuat tugas. Permintaan pembuatan video, musik, 3D, dan Worlds mengembalikan 409 dengan kode idempotency_conflict. Message Batches mengembalikan 409 dengan tipe error conflict_error. Untuk tugas gambar dan permintaan Responses dengan background: true, kode status dan kode error untuk kasus ini tidak dijamin. Jangan ulangi permintaan dengan key yang sama.
Chat Completions, Responses, dan Messages
POST /v1/chat/completions, POST /v1/responses tanpa background, dan POST /v1/messages menjalankan permintaan dengan key tertentu hanya sekali. Retry dengan key yang sama akan mendapatkan salah satu hasil berikut:
| Situasi | Hasil |
|---|---|
| Permintaan pertama masih berjalan | 409 dengan kode idempotency_replay_unavailable |
| Permintaan pertama selesai setelah klien Anda terputus. Permintaan tidak di-stream, hasilnya 1 MB atau lebih kecil, dan Anda melakukan retry dengan body yang sama dalam waktu 24 jam | 200 dengan body respons asli dan header Idempotent-Replayed: true. TokenLab tidak menjalankan atau menagih permintaan kembali |
| Key digunakan dengan cara lain, contohnya: Anda menerima hasil, permintaan di-stream, hasil lebih besar dari 1 MB, atau lebih dari 24 jam berlalu | 409 dengan kode idempotency_replay_unavailable |
| Body berbeda dari permintaan pertama | 409, biasanya dengan kode idempotency_conflict. Beberapa permintaan mengembalikan idempotency_replay_unavailable |
409 dengan kode apa pun berarti TokenLab tidak menjalankan kembali permintaan tersebut. Permintaan yang di-stream dengan key tidak dapat berjalan dua kali, tetapi TokenLab tidak dapat mengirim output-nya kembali.
Contoh ini melakukan retry pada permintaan Chat Completions yang mengalami timeout dengan key yang sama hingga mendapatkan hasilnya:
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()) # Save this key with your job record.
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 # No response: retry with the same key and body.
except openai.ConflictError as exc:
if exc.code != "idempotency_replay_unavailable":
raise
# The first attempt can still be running. A later retry returns its result.
raise RuntimeError(f"No result for Idempotency-Key {key}")Jika percobaan terakhir masih mengembalikan idempotency_replay_unavailable, TokenLab tidak dapat mengembalikan hasil tersebut. Kirim permintaan dengan key baru hanya jika menjalankan kembali dan penagihan kedua dapat diterima.
Simpan Request ID
Header respons menyertakan Request ID untuk pelacakan. Simpan ID tersebut bersama endpoint, model, waktu, dan ID pengguna atau pekerjaan Anda sendiri. Untuk pekerjaan asinkron, simpan juga task_id dan billing_transaction_id jika ada.
Saat menghubungi dukungan, sertakan ID tersebut dan contoh yang telah disunting. Jangan pernah mengirim API key, management token, media pribadi, signed URL, atau prompt pribadi yang lengkap.