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 lainnya 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 | Ubah izin key atau model |
404 | Sumber daya tidak ada atau tidak lagi tersedia | Periksa ID dan API key yang membuatnya |
413 | Permintaan atau file yang diunggah terlalu besar | Kurangi input ke batas model atau endpoint yang didokumentasikan |
429 | Batas permintaan tercapai | Tunggu sesuai Retry-After |
500–504 | Layanan tidak tersedia atau gangguan jaringan | Coba lagi hanya jika retryable bernilai true; patuhi retry_after dan batasi percobaan |
Kode error umum
| Kode | Apa artinya | Apa yang harus diubah |
|---|---|---|
invalid_api_key | Kunci API tidak ada, tidak valid, tidak aktif, atau telah dicabut | Periksa header Authorization dan nilai key |
expired_api_key | Kunci API 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 |
model_not_found | ID model tidak diketahui atau tidak tersedia | Baca /v1/models dan gunakan ID model saat ini |
context_length_exceeded | Input lebih panjang dari yang diterima model | Hapus riwayat atau pilih model dengan jendela konteks yang lebih besar |
rate_limit_exceeded | Terlalu banyak permintaan dikirim dalam jendela saat ini | Tunggu sesuai Retry-After |
payload_too_large | Body permintaan atau file melebihi batas endpoint | Kurangi atau kompres input |
all_channels_failed | Model yang dipilih tidak dapat melayani permintaan ini | Coba lagi 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 tidak ada pasokan untuk operasi pada tingkat Delivery yang dipilih, retryable bernilai false dan retry_after tidak dikembalikan. Jangan ulangi permintaan yang sama. Periksa ketersediaan operasi dan Delivery melalui GET /v1/models sebelum memilih model lain. Nama serupa tidak membuktikan ketersediaan; alternatif yang belum diverifikasi tidak ditampilkan.
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.
Jika permintaan berjalan melalui rute Official dan layanan upstream menolak permintaan itu sendiri, misalnya karena input yang tidak diterima atau keputusan kebijakan konten, error juga membawa upstream: message dari upstream sebagaimana dilaporkan, serta code dan source (nama layanan upstream) bila diketahui. Error Anthropic Messages dan Gemini membawa objek yang sama di dalam error masing-masing. Tetap tentukan penanganan berdasarkan 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 | Coba lagi hanya jika retryable bernilai true; patuhi retry_after dan batasi percobaan |
| Koneksi terputus sebelum ada respons | Terkadang. Untuk operasi pembuatan, periksa apakah tugas atau efek samping sudah ada. |
| Stream terputus setelah output tiba | Jangan anggap sebagai respons lengkap. Mengulangi mungkin menghasilkan output yang berbeda atau tagihan kedua. |
Untuk pembuatan gambar, video, musik, 3D, dan Worlds, simpan ID tugas segera setelah dikembalikan. Jika permintaan pembuatan mengalami timeout, periksa catatan tugas sebelum mengirim permintaan pembuatan lainnya.
Simpan Request ID
Header respons menyertakan Request ID untuk pelacakan. Simpan ID tersebut bersama endpoint, model, waktu, serta 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, token manajemen, media pribadi, signed URL, atau prompt pribadi yang lengkap.