Error dan status

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

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, NusaRouter 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.

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.nusarouter.web.id/v1", api_key="sk-nusa-...")

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"):
            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