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

StatusArtiTindakan umum
400Bidang, ID model, atau input tidak validPerbaiki permintaan; jangan ulangi tanpa perubahan
401API key hilang, tidak valid, kedaluwarsa, atau dicabutGanti key
402Saldo atau batas API-key terlalu rendahIsi ulang, naikkan batas, atau kurangi permintaan
403Key ini tidak dapat menggunakan sumber daya atau model tersebut, atau akun dibatasiUbah izin key atau model, atau hubungi dukungan
404Sumber daya tidak ada atau tidak lagi tersediaPeriksa ID dan API key yang membuatnya
409Idempotency-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 tersebutGunakan key baru untuk permintaan baru. Untuk memutuskan apakah akan melakukan retry dengan key yang sama, lihat Retry dengan aman menggunakan idempotency key
413Permintaan atau file yang diunggah terlalu besarKurangi input sesuai batas model atau endpoint yang didokumentasikan
429Batas permintaan tercapaiTunggu hingga Retry-After
500–504Layanan tidak tersedia atau kegagalan jaringanLakukan retry hanya jika retryable bernilai true; patuhi retry_after dan batasi percobaan

Kode error umum

KodeApa artinyaApa yang harus diubah
invalid_api_keyAPI key hilang, tidak valid, tidak aktif, atau dicabutPeriksa header Authorization dan nilai key
expired_api_keyKey telah kedaluwarsaBuat atau pilih key yang aktif
insufficient_balanceSaldo akun tidak mencukupi untuk permintaan tersebutTambahkan dana, kurangi permintaan, atau pilih model dengan harga lebih rendah
quota_exceededAPI key mencapai batasnya sendiriTingkatkan batas key tersebut atau gunakan key resmi lainnya
model_not_allowedKey tidak dapat menggunakan model yang dimintaPerbarui daftar model key atau pilih model yang diizinkan
user_suspended, account_restrictedHTTP 403. Akun tidak dapat menggunakan APIHubungi dukungan dengan menyertakan Request ID
invalid_delivery_policyHTTP 400. Header X-TokenLab-Delivery-Policy bukan auto, verified, atau officialKirim salah satu dari tiga nilai tersebut, atau hapus header
model_not_foundID model tidak diketahui atau tidak tersediaBaca /v1/models dan gunakan ID model yang saat ini berlaku
context_length_exceededInput lebih panjang dari yang diterima modelHapus riwayat atau pilih model dengan jendela konteks yang lebih besar
missing_required_parameterBidang wajib diisi hilang. param menyebutkan namanya, contohnya model pada permintaan audio dan gambar, yang tidak memiliki model defaultKirim bidang yang disebutkan oleh param
invalid_valueBidang memiliki nilai yang tidak diterima model, contohnya nilai reasoning_effort. Pesan mencantumkan nilai yang diterimaGunakan salah satu nilai yang tercantum
invalid_response_format_typeHTTP 400. response_format adalah objek tanpa type yang dapat digunakan, atau dengan type yang tidak diterima endpoint ini. param adalah response_formatSetel response_format.type ke text, json_object, atau json_schema; dengan json_schema, kirim juga json_schema.name dan json_schema.schema
invalid_image_urlTokenLab tidak dapat menggunakan URL gambar: bukan URL HTTP(S) atau URI data gambar yang valid, atau host gambar tidak mengembalikan gambar. param menyebutkan bidangnyaKirim URL gambar HTTPS publik atau URI data yang didukung
unsupported_model_capabilityTidak 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 didukungHapus atau ubah parameter, atau pilih Delivery tier atau model lain; jangan ulangi permintaan tanpa perubahan
unpriceable_selectionPermintaan video melewatkan pemilih yang menjadi dasar harganya, sehingga TokenLab tidak dapat menentukan harganya. param menyebutkan pemilihnyaAtur bidang yang disebutkan oleh param
model_pricing_unavailableHTTP 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 falseJangan ulangi permintaan tanpa perubahan; pilih model atau operasi lain, atau hubungi dukungan dengan menyertakan Request ID
idempotency_conflictHTTP 409. Idempotency-Key milik permintaan yang berbeda. TokenLab tidak menjalankan permintaan iniKirim permintaan baru dengan key baru
idempotency_replay_unavailableHTTP 409. Idempotency-Key sudah digunakan, dan TokenLab tidak memiliki hasil untuk dikembalikan. TokenLab tidak menjalankan kembali permintaan iniJika 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_replayableHTTP 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 iniJangan ulangi permintaan dengan key ini. Kirim key baru hanya jika Anda menginginkan tugas baru
rate_limit_exceededTerlalu banyak permintaan dikirim dalam jendela waktu saat iniTunggu hingga Retry-After
all_channels_failedModel yang dipilih tidak dapat melayani permintaan iniLakukan retry hanya jika retryable bernilai true; patuhi retry_after dan batasi percobaan
timeout_errorPermintaan tidak selesai tepat waktuLakukan 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

ErrorUlangi permintaan yang sama?
400, 401, 402, 403, 404, 413Tidak. Ubah permintaan, kredensial, saldo, izin, atau input.
429Ya, setelah penundaan yang diberikan server.
500–504Lakukan retry hanya jika retryable bernilai true; patuhi retry_after dan batasi percobaan
Koneksi terputus sebelum ada responsYa, 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 tibaJangan 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/batches berbeda: ia menolak key yang lebih panjang dari 256 karakter dengan 400.
  • Simpan key dengan catatan pekerjaan Anda sendiri sebelum mengirim permintaan.
  • Saat melakukan retry, kirim API key yang sama, Idempotency-Key yang sama, dan body yang sama.
  • Setelah respons apa pun selain 409 dengan idempotency_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, dan POST /v1/worlds/generations
  • POST /v1/images/generations dan POST /v1/images/edits saat mengembalikan tugas
  • POST /v1/responses dengan "background": true
  • POST /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:

SituasiHasil
Permintaan pertama masih berjalan409 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 jam200 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 berlalu409 dengan kode idempotency_replay_unavailable
Body berbeda dari permintaan pertama409, 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.

Dari permintaan ke investigasi dan dukungan

Di halaman ini