Error dan status
Bentuk error, tabel kode, dan cara menanganinya.
Di halaman ini7 bagianTutup
Ringkasan#
Setiap kegagalan dijawab dengan bentuk JSON yang sama, dan code di dalamnya yang menentukan apa yang harus kamu lakukan.
{
"error": {
"message": "Pesan yang aman untuk ditampilkan.",
"type": "invalid_request_error",
"code": "model_not_found"
}
}Body-nya selalu JSON. Status HTTP memberi tahu kelasnya, dan code memberi tahu yang sebenarnya terjadi. Percayai code, karena satu status bisa berarti dua hal berbeda.
Di permukaan Anthropic (POST /v1/messages), error memakai envelope Anthropic, dan validation di sana 400, bukan 422. Lihat Format Anthropic.
Tabel error#
Tiga puluh kode, urut menaik berdasarkan status. Satu status bisa berarti beberapa hal berbeda, jadi yang menentukan tindakanmu adalah code, bukan angkanya.
| HTTP | type | code | Artinya |
|---|---|---|---|
| 400 | invalid_request_error | invalid_request | Request tidak bisa diproses. Perbaiki bentuk body-nya, lalu kirim ulang. |
| 400 | invalid_request_error | context_length_exceeded | Input melebihi jendela konteks model. Ringkas atau potong riwayatnya, lalu ulangi; mengulang apa adanya tidak akan pernah muat. |
| 401 | authentication_error | invalid_api_key | API key hilang atau tidak dikenali. Kirim header Authorization dengan key yang masih aktif. |
| 401 | authentication_error | not_authenticated | Sesi konsol tidak ada atau sudah berakhir. Masuk ulang. |
| 401 | authentication_error | invalid_credentials | Email atau kata sandi salah saat masuk. Periksa keduanya; pesan ini sengaja tidak menyebut mana yang salah. |
| 402 | billing_error | insufficient_balance | Saldo dompet tidak cukup. Top up dulu. |
| 402 | billing_error | spending_limit_exceeded | Batas belanja key ini sudah habis. Naikkan batas key-nya, atau pakai key lain; top up tidak menolong. |
| 403 | permission_error | captcha_failed | Verifikasi captcha saat masuk gagal, jadi kredensialnya belum sempat diperiksa. Ulangi tantangannya; ini bukan salah kata sandi. |
| 403 | permission_error | forbidden | Tidak diizinkan untuk tindakan ini. Key atau perannya memang tidak punya akses ke situ. |
| 404 | invalid_request_error | model_not_found | Model tidak ada, atau path-nya tidak cocok dengan rute mana pun. Ambil id dari katalog dan periksa URL-nya. |
| 404 | invalid_request_error | user_not_found | Id pengguna tidak menunjuk akun mana pun. Periksa id-nya; ini dipakai saat menghapus pengguna dari konsol. |
| 404 | invalid_request_error | minimum_discount_not_met | Tidak ada penawaran yang masuk ke batas harga kita untuk model ini. Coba lagi nanti atau pakai model lain; ini bukan soal saldomu. |
| 404 | invalid_request_error | no_sellers_for_model | Model ini sedang tidak punya penawaran sama sekali. Pilih model lain; mengulang tidak akan mengubahnya. |
| 409 | invalid_request_error | conflict | Bertentangan dengan keadaan saat ini, biasanya karena dua perubahan bersamaan. Muat ulang keadaan terbaru, lalu ulangi. |
| 409 | invalid_request_error | payment_manual | Pembayaran otomatis sedang dimatikan; top up diselesaikan manual. Ikuti instruksi pembayaran manual di konsol. |
| 413 | invalid_request_error | request_too_large | Body request melewati batas ukuran (30 MiB). Kirim lebih kecil, atau unggah berkasnya lewat rute multipart yang sesuai. |
| 422 | invalid_request_error | invalid_request | Body request gagal validasi. Pesan errornya menyebut field yang bermasalah; perbaiki field itu. |
| 422 | invalid_request_error | capability_mismatch | Model menyatakan dirinya tidak melayani jenis permintaan ini. Pakai model lain; body-mu tidak perlu diubah. |
| 422 | invalid_request_error | capabilities_not_declared | Model belum mendeklarasikan kapabilitas yang dibutuhkan. Operator harus mengeset capabilities yang sesuai ke true lebih dulu; ini bukan sesuatu yang bisa kamu kirim di body. |
| 422 | invalid_request_error | invalid_reset_token | Tautan reset kata sandi tidak berlaku: tidak dikenal, kedaluwarsa, atau sudah dipakai. Minta tautan baru. |
| 422 | invalid_request_error | password_breached | Kata sandi yang dipilih muncul di kebocoran data yang dikenal. Pilih kata sandi lain; bentuknya valid, nilainya yang bermasalah. |
| 429 | rate_limit_error | rate_limit_exceeded | Batas per menit terlewati. Tunggu sesuai retry-after, lalu kirim lebih lambat. |
| 429 | rate_limit_error | concurrency_exceeded | Batas request bersamaan terlewati. Tunggu satu request selesai, atau kurangi paralelismenya; menunggu lebih lama tidak menolong. |
| 500 | server_error | internal_error | Kesalahan di sisi kami. Ulangi dengan jeda; kalau tetap terjadi, hubungi kami dengan waktu dan id request-nya. |
| 501 | server_error | not_implemented | Rutenya ada, kemampuannya belum dibangun. Mengulang tidak akan menolong. |
| 501 | server_error | surface_not_served | Endpoint ini belum tersedia untuk model tersebut di platform kami. Pakai model lain; ini bukan gangguan dan bukan kesalahan request-mu. |
| 502 | server_error | empty_completion | Model menjawab, tokennya sudah diproses, tapi tidak ada output yang bisa dibaca. Naikkan max_tokens atau ulangi; periksa pesan errornya untuk tahu apakah token yang diproses ditagih. |
| 502 | server_error | upstream_unavailable | Model di balik layar tidak bisa dihubungi. Tunggu sebentar, lalu ulangi. |
| 503 | server_error | no_healthy_sellers | Routing berjalan tapi tidak ada penawaran yang bisa melayani saat itu. Sifatnya sementara: ulangi beberapa saat lagi. |
| 504 | server_error | upstream_timeout | Model di balik layar kehabisan waktu. Ulangi dengan permintaan lebih pendek, atau tanpa streaming untuk jawaban panjang. |
Empat yang perlu diperhatikan#
empty_completion punya aturan biaya sendiri, dan itu mengikuti apakah tokenmu sempat diproses. Model menjawab 200 tapi tidak menghasilkan apa pun yang bisa dibaca. Kalau ada pemakaian yang tercatat, MenvoraRouter tetap menagihkan token yang sudah diproses, dan pesan errornya menyebutkan itu. Kalau tidak ada pemakaian yang tercatat, penahanannya dilepas penuh. Ia sengaja dibedakan dari upstream_unavailable: yang satu berarti modelnya jalan tapi tidak bicara, yang lain berarti modelnya tidak bisa dihubungi. Yang pertama kamu ulangi atau naikkan max_tokens; yang kedua kamu tunggu.
not_implemented (501) berbeda dari internal_error (500). 500 berarti sesuatu seharusnya bekerja tapi tidak. Ada gangguan. 501 berarti kemampuan itu memang belum dibangun. Kalau kamu menerima 501, mengulang tidak akan menolong.
model_not_found juga muncul untuk path yang tidak cocok dengan rute mana pun. Jadi kalau kamu salah mengetik path (misalnya lupa /v1), yang muncul model_not_found, bukan pesan tentang rute. Periksa URL-nya sebelum menyimpulkan bahwa id modelmu salah.
concurrency_exceeded berarti ada requestmu yang masih berjalan. Ia berbagi status 429 dengan rate_limit_exceeded, tapi penanganannya berbeda: yang pertama diatasi dengan membatasi paralelisme, yang kedua dengan menunggu.
Kegagalan khusus media#
Tiga penolakan ini tidak muncul karena body-mu salah, melainkan karena model yang kamu pilih tidak cocok dengan rute yang kamu panggil.
Setiap rute punya kapabilitas yang dituntutnya: chat untuk /v1/chat/completions, /v1/messages, dan /v1/decisions; image untuk kedua rute gambar; audio untuk kedua rute audio; dan embeddings untuk /v1/embeddings. Model ditanya lebih dulu, dan jawabannya dibaca dari capabilities di katalog. Ada tiga kemungkinan:
| HTTP dan code | Kapan muncul | Apa yang harus kamu lakukan |
|---|---|---|
422 capability_mismatch | Model menyatakan tidak: kapabilitas yang dibutuhkan tertulis false. Operator sudah memutuskan model ini bukan untuk jenis permintaan itu. | Pakai model lain. Body-mu tidak perlu diubah, dan mengulang tidak akan menolong. |
422 capabilities_not_declared | Model belum menyatakan apa pun: capabilities-nya null, atau objeknya tidak menyebut flag yang dibutuhkan. | Modelnya harus mendeklarasikan capabilities.<yang dibutuhkan> = true lebih dulu. Itu perubahan di sisi model, bukan sesuatu yang bisa kamu kirim di body. |
501 surface_not_served | Model ini tidak dilayani jalur media di platform ini, meskipun modelnya ada di katalog. Permintaannya benar; jalur media untuk model itu yang belum ada. | Pakai model lain yang memang dilayani rute tersebut. Ini bukan gangguan, jadi jangan diulang. |
capability_mismatch dan capabilities_not_declared sengaja dipisah meskipun statusnya sama, karena obatnya berbeda: yang pertama berarti "pakai model lain", yang kedua berarti "deklarasikan dulu". Menyatukan keduanya akan menyuruh operator mengganti model padahal baris di depannya cuma kurang satu field.
Cara memeriksa sebelum mengirim: baca capabilities dan price.unit di GET /v1/models atau di katalog publik. Yang tertulis di sana adalah yang dibaca gerbang ini, jadi tidak ada jawaban lain yang lebih benar.
Yang tidak pernah kami kirim#
Pesan error dibangun dari daftar kode yang tetap. Teks mentah dari model di balik layar tidak pernah diteruskan apa adanya, karena teks itu sering memantulkan konteks request. Di dalamnya bisa ada alamat internal, nama host, dan referensi akun.
Kalau sesuatu gagal di sisi kami, yang kamu terima pesan umum dengan status 500. Detailnya masuk ke log kami, bukan ke responsemu. Itu disengaja: detail internal di response cara paling umum sebuah sistem membocorkan dirinya sendiri.
Menangani error#
import time
from openai import OpenAI, APIStatusError
client = OpenAI(base_url="https://api.menvorainterasia.com/v1", api_key="sk-menv-...")
for attempt in range(5):
try:
r = client.chat.completions.create(
model="deepseek-flash-v4.1",
messages=[{"role": "user", "content": "Halo!"}],
)
break
except APIStatusError as e:
body = e.response.json().get("error", {})
code = body.get("code")
# Yang tidak akan membaik dengan diulang: hentikan, jangan ulangi.
if code in ("invalid_request", "model_not_found", "insufficient_balance",
"spending_limit_exceeded", "not_implemented",
"capability_mismatch", "capabilities_not_declared",
"surface_not_served", "context_length_exceeded"):
raise
# Batas laju: ikuti retry-after, jangan menebak jedanya.
if e.status_code == 429:
time.sleep(float(e.response.headers.get("retry-after", "1")))
continue
# 5xx dari sisi kami: mundur eksponensial.
time.sleep(2 ** attempt)
else:
raise RuntimeError("menyerah setelah 5 percobaan")Aturan yang paling sering diabaikan: jangan mengulang error yang tidak akan membaik dengan diulang. Mengulang invalid_request atau model_not_found hanya menghasilkan request yang sama gagal berkali-kali, dan untuk error saldo ia menambah beban tanpa mengubah apa pun.
Troubleshooting#
| Gejala | Penyebab | Solusi |
|---|---|---|
401 | Key tidak terkirim atau sudah dicabut. | lihat Autentikasi |
404 model_not_found | Id model salah, atau path-nya tidak cocok dengan rute mana pun. | cek id dari katalog, dan cek URL-nya berakhir /v1/chat/completions |
402 | Saldo dompet habis, atau batas belanja key habis. | lihat code-nya: insufficient_balance berarti top up, spending_limit_exceeded berarti naikkan batas key |
429 | Batas per menit atau batas konkurensi. | tunggu retry-after, atau batasi paralelisme; lihat Batas laju |
502 | Model tidak bisa dihubungi (upstream_unavailable), atau menjawab tanpa output yang bisa dibaca (empty_completion). | cek pesan errornya untuk tahu yang mana. Kalau pesannya menyebut biaya, mengulang berarti membayar lagi, jadi perbaiki dulu penyebabnya |
504 | Model kehabisan waktu. | ulangi dengan request yang lebih pendek, atau tanpa streaming untuk jawaban panjang |