> ## Documentation Index
> Fetch the complete documentation index at: https://docs.triw.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Error dan troubleshooting

> Struktur error, tabel kode, dan perbaikan yang benar-benar menyelesaikan tiap kasus.

## Struktur error

Endpoint chat, embedding, image, dan audio mengembalikan error berbentuk OpenAI:

```json theme={null}
{
  "error": {
    "message": "insufficient user quota",
    "type": "new_api_error",
    "code": "insufficient_user_quota"
  }
}
```

Pakai `code` di logika program, `message` untuk log manusia. Pesan bisa berubah; kode stabil.

## Daftar kode

| `code` | HTTP | Arti | Perbaikan |
| - | - | - | - |
| `invalid_api_key` | 401 | Key tidak ada, salah format, atau tidak dikenal | Kirim `Authorization: Bearer sk-...`; pastikan key tidak dinonaktifkan |
| `insufficient_user_quota` | 403 | Saldo akun habis, atau kuota key itu sendiri tercapai | Top-up, atau naikkan/hapus kuota key |
| `insufficient_quota` | 429 | Provider upstream melaporkan kuotanya habis | Coba lagi nanti atau pindah model |
| `model_not_found` | 404 | Model tidak tersedia untuk grup key ini | Cek `GET /v1/models` dengan key yang sama |
| `rate_limit` | 429 | Terlalu banyak request untuk key atau channel | Backoff, gunakan retry eksponensial |
| `channel_error` | 502 | Channel upstream gagal, dimatikan, atau timeout | Retry; bila menetap, laporkan model dan waktunya |
| `invalid_request_error` | 400 | Body ditolak sebelum mencapai upstream | Validasi JSON, field wajib, nama parameter |

## Troubleshooting per gejala

### `401 invalid_api_key` padahal key terlihat benar

1. Tidak ada spasi atau tanda kutip yang ikut tersimpan di environment variable.
2. Header harus `Authorization: Bearer <key>` — bukan `x-api-key` di route OpenAI.
3. Key milik deployment Triw yang sama (base URL `https://router.triw.io`).
4. Key tidak dinonaktifkan dan belum kedaluwarsa (console menampilkan keduanya).

### Berhasil di curl, gagal di SDK

Biasanya path ganda: SDK menambahkan `/chat/completions` ke base URL, jadi base harus `https://router.triw.io/v1` — jangan `https://router.triw.io/v1/chat/completions`.

### `model_not_found` untuk model yang terlihat di halaman pricing

Halaman pricing mencakup semua grup. Grup key Anda lebih sempit. Buat key di grup yang tepat atau minta operator mengaktifkan model untuk grup Anda.

### Streaming berhenti di tengah jawaban

Proxy dan network melakukan buffering. Jika ada reverse proxy sendiri di depan klien, matikan buffering response untuk `/v1/*` dan naikkan read timeout di atas 300 detik. Triw sendiri meneruskan stream sampai upstream selesai.

### Request panjang gagal dengan 5xx

Model reasoning bisa menahan koneksi beberapa menit. Set timeout klien minimal 600 detik untuk model seperti itu, dan utamakan streaming agar koneksi tetap hidup.

### `channel_error` melonjak tiba-tiba

Biasanya satu channel upstream sedang bermasalah. Retry dengan backoff; kalau model yang sama gagal lebih dari beberapa menit, ganti model atau laporkan.

## Saat melaporkan masalah

Sertakan: waktu beserta zona waktu, nama model, `code` dari body error, dan request id dari response header bila ada. Data itu langsung memetakan ke entri log.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.