Error & Debugging

Halaman ini adalah referensi lengkap kegagalan pada API Nexotao: bentuk body error, arti tiap kode, mana yang boleh diulang, dan cara melacak satu permintaan setelah kejadian.

Base URL: https://api.nexotao.com.

Amplop error

Setiap error dari API dikembalikan sebagai satu objek JSON dengan bentuk yang sama, apa pun endpoint-nya.

{
  "error": "invalid api key",
  "code": "auth.api_key_invalid",
  "type": "api_key_invalid",
  "request_id": "8997bda3-65c4-45c3-ab38-c909f905fc4d",
  "retryable": false
}

Dua header selalu menyertai respons error:

Membaca kode error

curl -sS -D /tmp/h.txt https://api.nexotao.com/v1/chat/completions \
  -H "Authorization: Bearer sk-nexo-CONTOH-PALSU" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-6","messages":[{"role":"user","content":"halo"}]}'
 
grep -i '^x-error-code\|^x-request-id' /tmp/h.txt

import httpx
 
r = httpx.post(
    "https://api.nexotao.com/v1/chat/completions",
    headers={"Authorization": "Bearer sk-nexo-CONTOH-PALSU"},
    json={"model": "claude-sonnet-4-6",
          "messages": [{"role": "user", "content": "halo"}]},
)
 
if r.status_code >= 400:
    body = r.json()
    print(body["code"], body["request_id"], body["retryable"])
    # header juga cukup, tanpa parsing body:
    print(r.headers["x-error-code"], r.headers["x-request-id"])

const res = await fetch("https://api.nexotao.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk-nexo-CONTOH-PALSU",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-6",
    messages: [{ role: "user", content: "halo" }],
  }),
})
 
if (!res.ok) {
  const body = await res.json()
  console.error(body.code, body.request_id, body.retryable)
  console.error(res.headers.get("x-error-code"), res.headers.get("x-request-id"))
}

request_id

Setiap permintaan — berhasil maupun gagal — mendapat request_id unik yang dikirim di header X-Request-Id dan dicatat di sisi server.

• Pada respons error, id yang sama juga ada di body sebagai request_id.
• Simpan id ini di log aplikasi Anda. Saat melapor ke dukungan, satu request_id jauh lebih berguna daripada tangkapan layar pesan error.
• Untuk permintaan streaming, X-Request-Id dikirim sebelum byte pertama stream, jadi ia tetap terbaca meski stream gagal di tengah jalan.

curl -sS -D - -o /dev/null https://api.nexotao.com/v1/messages \
  -H "Authorization: Bearer sk-nexo-CONTOH-PALSU" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":16,
       "messages":[{"role":"user","content":"halo"}]}' \
  | grep -i x-request-id

Katalog kode error

Dikelompokkan per status HTTP. Kolom Retry adalah nilai field retryable pada body.

400 — Permintaan tidak valid

401 — Autentikasi gagal

402 — Saldo

Pemeriksaan ini terjadi sebelum permintaan diteruskan ke model, jadi permintaan yang ditolak 402 tidak menagih apa pun.

403 — Ditolak

404 / 405 — Rute

413 — Body terlalu besar

429 — Rate limit dan kuota

Pada jalur API key, respons juga membawa header observabilitas laju bila fitur terkait aktif untuk key tersebut:

5xx — Gangguan sisi server

Error in-band pada streaming

Ini bagian paling mudah terlewat di seluruh API.

Bentuk event error berbeda menurut endpoint:

data: {"error":{"message":"upstream service unavailable after retries; please retry","type":"server_error","code":"upstream_unavailable","request_id":"8997bda3-65c4-45c3-ab38-c909f905fc4d"}}

data: [DONE]

event: error
data: {"type":"error","error":{"type":"overloaded_error","message":"upstream service unavailable after retries; please retry","request_id":"8997bda3-65c4-45c3-ab38-c909f905fc4d"}}

data: [DONE]

event: response.failed
data: {"type":"response.failed","response":{"id":"resp_8997bda3-65c4-45c3-ab38-c909f905fc4d","object":"response","status":"failed","output":[],"error":{"message":"upstream service unavailable after retries; please retry","type":"server_error","code":"upstream_unavailable"}}}

Pesannya adalah teks tetap yang dipilih dari klasifikasi kegagalan — mis. “upstream capacity exhausted after waiting; please retry” untuk throttle, “upstream timed out before starting the stream; please retry” untuk timeout, atau pesan spesifik untuk context window yang terlampaui. Kalau ada saran yang relevan (mis. arahan pemilihan model), saran itu ditempelkan ke akhir pesan, karena stream tidak punya tempat untuk field hint terpisah.

Contoh deteksi

import json, httpx
 
payload = {
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "halo"}],
    "stream": True,
}
 
with httpx.stream(
    "POST", "https://api.nexotao.com/v1/chat/completions",
    headers={"Authorization": "Bearer sk-nexo-CONTOH-PALSU"},
    json=payload, timeout=None,
) as r:
    request_id = r.headers.get("x-request-id")
    r.raise_for_status()  # perlu, TAPI tidak cukup
 
    for line in r.iter_lines():
        if not line.startswith("data: "):
            continue
        data = line[6:]
        if data == "[DONE]":
            break
        chunk = json.loads(data)
        if "error" in chunk:                     # kegagalan in-band
            err = chunk["error"]
            raise RuntimeError(
                f"{err.get('code')}: {err.get('message')} (request_id={request_id})"
            )
        # ... proses chunk normal

const res = await fetch("https://api.nexotao.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk-nexo-CONTOH-PALSU",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-6",
    messages: [{ role: "user", content: "halo" }],
    stream: true,
  }),
})
 
const requestId = res.headers.get("x-request-id")
if (!res.ok) throw new Error(`HTTP ${res.status} (request_id=${requestId})`)
 
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader()
let buffer = ""
 
for (;;) {
  const { value, done } = await reader.read()
  if (done) break
  buffer += value
 
  let idx
  while ((idx = buffer.indexOf("\n\n")) !== -1) {
    const event = buffer.slice(0, idx)
    buffer = buffer.slice(idx + 2)
 
    const dataLine = event.split("\n").find((l) => l.startsWith("data: "))
    if (!dataLine) continue
    const data = dataLine.slice(6)
    if (data === "[DONE]") continue
 
    const chunk = JSON.parse(data)
    if (chunk.error) {
      throw new Error(
        `${chunk.error.code}: ${chunk.error.message} (request_id=${requestId})`,
      )
    }
    // ... proses chunk normal
  }
}

Panduan retry

import json, random, time, httpx
 
NON_RETRYABLE_HTTP = {400, 401, 402, 403, 404, 405, 413}
 
def call_with_retry(client, url, headers, payload, max_attempts=5):
    delay = 1.0
    for attempt in range(max_attempts):
        r = client.post(url, headers=headers, json=payload)
        if r.status_code < 400:
            return r
 
        body = {}
        try:
            body = r.json()
        except json.JSONDecodeError:
            pass
 
        # Kontraknya adalah `retryable`, bukan status HTTP.
        if not body.get("retryable", r.status_code not in NON_RETRYABLE_HTTP):
            raise RuntimeError(
                f"{body.get('code')}: {body.get('error')} "
                f"(request_id={r.headers.get('x-request-id')})"
            )
 
        wait = delay
        if ra := r.headers.get("retry-after"):
            try:
                wait = max(wait, min(int(ra), 3600))
            except ValueError:
                pass
        time.sleep(wait + random.uniform(0, 0.5 * wait))   # jitter
        delay *= 2
 
    raise RuntimeError("kehabisan percobaan")

Biaya dan penelusuran setelah kejadian

Respons non-streaming membawa biaya aktual di header:

Pada respons SSE (streaming), X-Cost-Rp sengaja tidak dikirim: header harus ditulis sebelum byte pertama, sementara biaya baru diketahui setelah stream selesai.

Jadi untuk permintaan streaming, cara mengetahui biayanya adalah:

Lewat jalur mana pun, catatan finalnya memuat field berikut. Dua di antaranya perlu dipahami:

Field status memberi tahu hasil akhirnya, khususnya apakah permintaan yang gagal itu ditagih atau tidak:

Troubleshooting

401 auth.api_key_missing — header autentikasi tidak terkirim. Pada curl, periksa tanda kutip dan baris lanjutan (\). Pada SDK, pastikan base_url/baseURL menunjuk ke https://api.nexotao.com/v1 dan key benar-benar ter-set (bukan variabel lingkungan kosong).

401 auth.api_key_invalid — key tidak dikenali. Penyebab paling sering: spasi atau baris baru ikut tersalin, key milik lingkungan lain, atau key sudah dihapus. Buat key baru di dashboard. Lihat Autentikasi.

402 billing.insufficient_balance — saldo tidak cukup untuk menutup estimasi input plus jawaban minimal. Nexotao memeriksa ini sebelum memanggil model, jadi permintaan yang ditolak tidak menagih apa pun. Top-up lewat dashboard; lihat Penagihan & Harga.

429 rate_limit.rpm_exceeded / rate_limit.tpm_exceeded — batas per menit key terlampaui. Turunkan konkurensi, terapkan backoff, atau kecilkan prompt/max_tokens. Header X-RateLimit-* menunjukkan sisa kuota dan detik sampai jendela berganti.

429 quota.key_limit_exceeded — batas belanja key tercapai. Ini pagu anggaran yang Anda sendiri pasang di dashboard, bukan throttle laju. Naikkan atau matikan limitnya di sana.

400 model.unknown — id model salah ketik atau model sudah tidak aktif. Ambil daftar yang sah:

curl -sS https://api.nexotao.com/v1/models \
  -H "Authorization: Bearer sk-nexo-CONTOH-PALSU"

404 route.not_found — path tidak dilayani. Yang paling sering: klien OpenAI-generik memanggil /v1/images/generations atau /v1/audio/transcriptions. Kedua endpoint itu tidak tersedia di Nexotao — lihat daftar endpoint yang dilayani di API Reference.

Stream berakhir tanpa teks, tanpa error — hampir selalu error in-band yang tidak diparse klien Anda. Kembali ke bagian Error in-band pada streaming di atas, lalu cari id permintaan itu di halaman Usage pada dashboard: status aborted_stream atau upstream_error menegaskan permintaan itu gagal dan tidak ditagih.

Masih buntu? Kumpulkan request_id, code, dan waktu kejadian, lalu hubungi dukungan lewat dashboard. Tanpa request_id, satu permintaan hampir tidak mungkin ditemukan di log.