Lewati ke isi dokumentasi
Error dan status

Error dan status

Bentuk error, tabel kode, dan cara menanganinya.

Referensi API7 bagianAPI v1
Di halaman ini7 bagian

Ringkasan#

Setiap kegagalan dijawab dengan bentuk JSON yang sama, dan code di dalamnya yang menentukan apa yang harus kamu lakukan.

bentuk error
{
  "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.

HTTPtypecodeArtinya
400invalid_request_errorinvalid_requestRequest tidak bisa diproses. Perbaiki bentuk body-nya, lalu kirim ulang.
400invalid_request_errorcontext_length_exceededInput melebihi jendela konteks model. Ringkas atau potong riwayatnya, lalu ulangi; mengulang apa adanya tidak akan pernah muat.
401authentication_errorinvalid_api_keyAPI key hilang atau tidak dikenali. Kirim header Authorization dengan key yang masih aktif.
401authentication_errornot_authenticatedSesi konsol tidak ada atau sudah berakhir. Masuk ulang.
401authentication_errorinvalid_credentialsEmail atau kata sandi salah saat masuk. Periksa keduanya; pesan ini sengaja tidak menyebut mana yang salah.
402billing_errorinsufficient_balanceSaldo dompet tidak cukup. Top up dulu.
402billing_errorspending_limit_exceededBatas belanja key ini sudah habis. Naikkan batas key-nya, atau pakai key lain; top up tidak menolong.
403permission_errorcaptcha_failedVerifikasi captcha saat masuk gagal, jadi kredensialnya belum sempat diperiksa. Ulangi tantangannya; ini bukan salah kata sandi.
403permission_errorforbiddenTidak diizinkan untuk tindakan ini. Key atau perannya memang tidak punya akses ke situ.
404invalid_request_errormodel_not_foundModel tidak ada, atau path-nya tidak cocok dengan rute mana pun. Ambil id dari katalog dan periksa URL-nya.
404invalid_request_erroruser_not_foundId pengguna tidak menunjuk akun mana pun. Periksa id-nya; ini dipakai saat menghapus pengguna dari konsol.
404invalid_request_errorminimum_discount_not_metTidak ada penawaran yang masuk ke batas harga kita untuk model ini. Coba lagi nanti atau pakai model lain; ini bukan soal saldomu.
404invalid_request_errorno_sellers_for_modelModel ini sedang tidak punya penawaran sama sekali. Pilih model lain; mengulang tidak akan mengubahnya.
409invalid_request_errorconflictBertentangan dengan keadaan saat ini, biasanya karena dua perubahan bersamaan. Muat ulang keadaan terbaru, lalu ulangi.
409invalid_request_errorpayment_manualPembayaran otomatis sedang dimatikan; top up diselesaikan manual. Ikuti instruksi pembayaran manual di konsol.
413invalid_request_errorrequest_too_largeBody request melewati batas ukuran (30 MiB). Kirim lebih kecil, atau unggah berkasnya lewat rute multipart yang sesuai.
422invalid_request_errorinvalid_requestBody request gagal validasi. Pesan errornya menyebut field yang bermasalah; perbaiki field itu.
422invalid_request_errorcapability_mismatchModel menyatakan dirinya tidak melayani jenis permintaan ini. Pakai model lain; body-mu tidak perlu diubah.
422invalid_request_errorcapabilities_not_declaredModel belum mendeklarasikan kapabilitas yang dibutuhkan. Operator harus mengeset capabilities yang sesuai ke true lebih dulu; ini bukan sesuatu yang bisa kamu kirim di body.
422invalid_request_errorinvalid_reset_tokenTautan reset kata sandi tidak berlaku: tidak dikenal, kedaluwarsa, atau sudah dipakai. Minta tautan baru.
422invalid_request_errorpassword_breachedKata sandi yang dipilih muncul di kebocoran data yang dikenal. Pilih kata sandi lain; bentuknya valid, nilainya yang bermasalah.
429rate_limit_errorrate_limit_exceededBatas per menit terlewati. Tunggu sesuai retry-after, lalu kirim lebih lambat.
429rate_limit_errorconcurrency_exceededBatas request bersamaan terlewati. Tunggu satu request selesai, atau kurangi paralelismenya; menunggu lebih lama tidak menolong.
500server_errorinternal_errorKesalahan di sisi kami. Ulangi dengan jeda; kalau tetap terjadi, hubungi kami dengan waktu dan id request-nya.
501server_errornot_implementedRutenya ada, kemampuannya belum dibangun. Mengulang tidak akan menolong.
501server_errorsurface_not_servedEndpoint ini belum tersedia untuk model tersebut di platform kami. Pakai model lain; ini bukan gangguan dan bukan kesalahan request-mu.
502server_errorempty_completionModel 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.
502server_errorupstream_unavailableModel di balik layar tidak bisa dihubungi. Tunggu sebentar, lalu ulangi.
503server_errorno_healthy_sellersRouting berjalan tapi tidak ada penawaran yang bisa melayani saat itu. Sifatnya sementara: ulangi beberapa saat lagi.
504server_errorupstream_timeoutModel 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 codeKapan munculApa yang harus kamu lakukan
422 capability_mismatchModel 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_declaredModel 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_servedModel 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#

Python
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#

GejalaPenyebabSolusi
401Key tidak terkirim atau sudah dicabut.lihat Autentikasi
404 model_not_foundId model salah, atau path-nya tidak cocok dengan rute mana pun.cek id dari katalog, dan cek URL-nya berakhir /v1/chat/completions
402Saldo dompet habis, atau batas belanja key habis.lihat code-nya: insufficient_balance berarti top up, spending_limit_exceeded berarti naikkan batas key
429Batas per menit atau batas konkurensi.tunggu retry-after, atau batasi paralelisme; lihat Batas laju
502Model 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
504Model kehabisan waktu.ulangi dengan request yang lebih pendek, atau tanpa streaming untuk jawaban panjang