Error koneksi umum dan cara mengatasinya

Hampir setiap masalah koneksi bermuara pada empat hal: alamat, kunci, ID model, dan saldo. Mulailah dengan pemeriksaan cepat di bawah, lalu temukan kode status Anda. Body respons yang dikutip di sini adalah respons API yang sebenarnya (Oktober 2026).

Pemeriksaan cepat#

# 1. The address is reachable — this request needs no key
curl https://api.cheaptokens.dev/v1/models

# 2. The key and the balance work — a tiny request (costs a fraction of a cent)
curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer $CHEAPTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-ai/DeepSeek-V4-Flash-0731", "max_tokens": 5,
       "messages": [{"role": "user", "content": "ping"}]}'

Jika perintah pertama gagal, penyebabnya bisa jadi jaringan di sisi Anda, salah ketik pada alamat — atau layanan itu sendiri yang sedang tidak tersedia. Jika hanya perintah kedua yang gagal, cari kode statusnya di bawah. Jika keduanya berhasil tetapi alat Anda tidak, bandingkan pengaturan alat tersebut dengan kedua perintah ini.

401 — Kunci API tidak valid#

{"error": {"message": "Invalid API key", "type": "authentication_error"}}

Klien bergaya Anthropic mendapat error yang sama dalam formatnya:

{"type": "error", "error": {"type": "authentication_error", "message": "Invalid API key"}}

Penyebab:

• kunci disalin dengan karakter yang hilang, spasi, atau tanda kutip;
• kunci dirotasi di dashboard — kunci lama tidak lagi berfungsi;
• kunci dari layanan lain (misalnya OpenAI) dipasang alih-alih kunci CheapTokens;
• variabel lingkungan kosong di terminal ini: echo ${#CHEAPTOKENS_API_KEY} mencetak panjangnya.

Dashboard hanya menampilkan kunci satu kali. Jika hilang, tekan Rotate untuk mendapatkan kunci baru dan perbarui di semua tempat yang menggunakannya.

402 — saldo kosong atau tidak ada kunci dalam permintaan#

API mengembalikan 402 dalam dua situasi berbeda:

1. Saldo habis. Permintaan dibayar dari saldo; saat habis, kunci dijeda. Isi ulang di dashboard dan permintaan akan berjalan lagi.
2. Permintaan tidak memiliki kunci sama sekali. Jika header Authorization (atau x-api-key untuk klien bergaya Anthropic) tidak ada, API menjawab 402 dengan tipe insufficient_funds. Periksa bahwa alat Anda benar-benar mengirim kunci: gaya OpenAI adalah Authorization: Bearer <key>.

404 — alamat salah#

{"error": {"message": "Invalid URL (GET /v1/chat/completion)", "type": "invalid_request_error", "param": null, "code": null}}

Jalurnya salah ketik — di sini completion alih-alih completions. Penyebab umum lainnya:

• Base URL tidak memiliki /v1. Klien bergaya OpenAI memerlukan https://api.cheaptokens.dev/v1. Tanpa /v1 permintaan tidak sampai ke API dan Anda mendapat halaman 404 HTML biasa alih-alih JSON.
• /v1 dua kali. Beberapa klien menambahkan /v1 sendiri; maka base URL harus berupa root, https://api.cheaptokens.dev. Klien bergaya Anthropic selalu menggunakan alamat root.

400 — model tidak ditemukan#

{"error": {"message": "Model \"deepseek-v4-flash\" not found. Available: …", "type": "invalid_request_error", "param": "model"}}

ID model harus berupa ID lengkap, termasuk awalan sebelum garis miring: deepseek-ai/DeepSeek-V4-Flash-0731, bukan deepseek-v4-flash. Huruf besar atau kecil tidak masalah. Pesan error mencantumkan ID yang tersedia, dan daftar lengkapnya selalu ada di GET /v1/models.

400 juga dikembalikan untuk body permintaan yang cacat — misalnya array messages yang kosong (messages field is required and must be a non-empty array) atau pesan tanpa role.

413 — permintaan terlalu besar#

Body permintaan dibatasi hingga 16 MB. Agen dapat mencapainya dengan memasukkan file atau log berukuran besar ke dalam konteks. Kirim hanya bagian yang dibutuhkan model dan pangkas output alat yang panjang.

429 — terlalu banyak permintaan#

Jika Anda menerima 429, perlambat. Responsnya menyertakan header Retry-After dengan jumlah detik untuk menunggu. SDK OpenAI resmi mencoba ulang secara otomatis (max_retries); dalam kode Anda sendiri, tunggu Retry-After sebelum percobaan berikutnya.

503 — model sementara tidak tersedia#

Sebuah model dapat sementara tidak tersedia; API kemudian menjawab 503 dengan tipe model_unavailable, dan kartu model di situs menampilkan "temporarily unavailable". Coba lagi nanti atau ganti bidang model ke model lain — kunci dan alamatnya tetap sama.

Waktu tunggu lama dan timeout#

Model penalaran seperti zai-org/GLM-5.3-Flash berpikir sebelum menjawab, sehingga token pertama bisa memakan waktu. Gunakan streaming atau naikkan timeout klien — misalnya timeout=120 di SDK OpenAI.