Panduan

Kesalahan, batas, dan percobaan ulang

Baca respons kesalahan dan header batas laju, coba ulang dengan aman, dan diagnosis gangguan umum.

Setiap Felo API mengembalikan isi error JSON dengan kode error yang stabil dan ID permintaan. Baca status HTTP terlebih dahulu, lalu code, lalu message.

Envelope Error

Respons produksi saat ini menggunakan status HTTP sebagai status:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid API Key",
  "request_id": "202610221444486982113280416060637185"
}

Field	Arti
`status`	Kode status HTTP, diulang di dalam body
`code`	Kode error yang dapat dibaca mesin
`message`	Penjelasan yang dapat dibaca manusia
`request_id`	Pengenal buram untuk permintaan ini; sertakan dalam permintaan dukungan

Sebagian contoh endpoint lama menggunakan status: "error" dan string kode yang berbeda. Bercabanglah berdasarkan status HTTP dan code, bukan berdasarkan kata-kata persis pada message.

Kode Umum

HTTP	Kode	Artinya	Yang harus dilakukan
400	Kode validasi spesifik endpoint	Ada parameter yang hilang atau tidak valid	Perbaiki permintaan; jangan mencoba ulang tanpa perubahan
401	`UNAUTHORIZED`	Kunci API hilang, tidak valid, kedaluwarsa, atau dicabut	Kirim `Authorization: Bearer $FELO_API_KEY`; rotasi kunci jika dicabut
402	`INSUFFICIENT_CREDITS`	Kredit layanan tidak mencukupi	Isi ulang di Console Billing, lalu coba lagi
404	Spesifik endpoint	Model, tugas, atau rute tidak dikenal	Periksa ID model atau ID tugas serta path endpoint
429	`RATE_LIMITED`	Batas laju terlampaui	Tunggu `Retry-After`, lalu coba lagi
5xx	`CHAT_FAILED`, `*_FAILED`, `SERVICE_UNAVAILABLE`	Kegagalan upstream atau layanan	Coba ulang dengan backoff; hubungi dukungan jika berlanjut

Referensi endpoint mencantumkan kode yang spesifik untuk endpoint tersebut. Mulai dengan error pada Chat API atau referensi endpoint yang Anda panggil.

Endpoint Generasi Model

POST /api/v1/images/generations dan POST /api/v1/videos/generations mengembalikan error tingkat endpoint dalam envelope OpenAI, bukan envelope di atas:

{
  "error": {
    "message": "Model kind does not match this generation endpoint",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_kind_mismatch"
  }
}

ID permintaan berada di header respons X-Request-Id, bukan di dalam body. Permintaan yang ditolak tidak membuat tugas. Setelah tugas ada, sebagian besar kegagalan datang sebagai status tugas terminal dalam respons 200, bukan sebagai error HTTP: periksa status untuk nilai failed atau interrupted, lalu baca error.message. Lihat Generasi Gambar dan Tugas Asinkron.

ID Permintaan

Body error Felo menyertakan request_id. Catat ID tersebut bersama endpoint, status HTTP, kode error, ID model, dan ID tugas. Jangan pernah mencatat kunci API lengkap.

Model API juga menerima header permintaan opsional X-Request-Id. Saat Anda mengirimkannya, header tersebut dikembalikan untuk diagnostik, sehingga Anda dapat mengorelasikan log Anda sendiri dengan suatu permintaan. Jika Anda tidak mengirimkannya, gunakan request_id yang dikembalikan.

Batas Laju

/v2/chat adalah satu-satunya endpoint Felo dengan batas laju yang diberlakukan dan didokumentasikan:

Per kunci API, jendela 1 menit.
Per pengguna, jendela 1 menit.
Per pengguna, jendela 1 jam.

Pengguna dengan langganan Felo berbayar yang efektif, termasuk langganan enterprise, dikecualikan dan tidak menerima header X-RateLimit-*. Jika status langganan tidak dapat diverifikasi, batas tetap berlaku.

Header	Arti
`X-RateLimit-Limit`	Batas dari dimensi paling ketat yang saat ini berlaku
`X-RateLimit-Remaining`	Kuota tersisa minimum di antara ketiga dimensi
`X-RateLimit-Reset`	Stempel waktu Unix dalam detik saat jendela saat ini direset
`Retry-After`	Pada 429, penundaan yang direkomendasikan dalam detik

Endpoint /v2/** lainnya saat ini tidak memiliki batas laju yang diberlakukan. Permintaan Model API tetap dapat dibatasi oleh penyedia upstream, yang dapat muncul sebagai 429.

Jangan menuliskan batas numerik secara hardcode. Baca header pada setiap respons.

Kebijakan Percobaan Ulang

Situasi	Coba ulang?
400, 401, 402, 404	Tidak. Perbaiki permintaan, kunci, atau saldo terlebih dahulu.
429	Ya, setelah `Retry-After` atau `X-RateLimit-Reset`.
5xx, batas waktu, koneksi direset	Ya, dengan backoff eksponensial dan jitter.
Koneksi streaming terputus di tengah respons	Coba ulang hanya jika aplikasi Anda dapat menoleransi generasi duplikat.

Perulangan yang direkomendasikan:

Coba ulang hanya permintaan yang idempoten atau aman diulang.
Gunakan backoff eksponensial: mulai sekitar 1 detik, gandakan, batasi pada 30 detik.
Tambahkan jitter acak agar klien tidak mencoba ulang secara serempak.
Berhenti setelah sejumlah kecil percobaan dan tampilkan error.
Pada 429, patuhi Retry-After alih-alih jadwal Anda sendiri.

Urutan Debugging

Periksa bahwa kunci ada dan tidak dicabut.
Panggil GET /api/v1/models dengan kunci yang sama untuk memastikan autentikasi.
Kirim permintaan valid terkecil ke endpoint target.
Tambahkan streaming, alat, atau input besar satu per satu.
Untuk pekerjaan asinkron, periksa status tugas sebelum mengirim ulang.