Error yang dapat ditindaklanjuti oleh agen

Halaman ini menjelaskan kesalahan API publik yang dapat dibaca aplikasi dan agen pemrograman. Ini tidak memberikan akses investigasi permintaan workspace atau dukungan. Mulai dari 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 tindakan yang harus diambil.

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

Kolom error opsionalCopy Anchor Link

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

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

Model tidak diketahuiCopy Anchor Link

Model yang salah ketik atau tidak tersedia akan mengembalikan 400 model_not_found. Jika did_you_mean tersedia, tampilkan kepada pengguna atau lakukan percobaan ulang 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 https://api.tokenlab.sh/v1/models to list all available models."
  }
}

Saldo tidak mencukupiCopy Anchor Link

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

{
  "error": {
    "message": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-6, but balance is $0.1200.",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gpt-5.6-luna"},
      {"id": "deepseek-v3-2"}
    ],
    "hint": "Try a cheaper model, or top up at https://tokenlab.sh/dashboard/billing."
  }
}

Model tidak tersediaCopy Anchor Link

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.

{
  "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)Copy Anchor Link

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

{
  "error": {
    "message": "Rate limit: 1000 rpm exceeded",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Retry after 8s."
  }
}

Konteks terlalu panjangCopy Anchor Link

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 tepatCopy Anchor Link

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

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

Menemukan model berdasarkan tugasCopy Anchor Link

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, dan translation. Kirimkan ID model yang dipilih secara eksplisit dalam permintaan pembuatan. TokenLab tidak akan menggantinya secara diam-diam dengan model lain.

Ringkasan yang dapat dibaca mesinCopy Anchor Link

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.

Tangani kesalahan tanpa mengirim ulang permintaanCopy Anchor Link

Contoh ini mengirim satu permintaan, mempertahankan model yang dipilih, dan menampilkan informasi kesalahan terstruktur. Percobaan ulang otomatis SDK dinonaktifkan. Minta pilihan eksplisit untuk saran model; jangan otomatis mengirim ulang pembuatan yang sudah diterima atau melewati batas waktu.

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