Panduan

Ralat, had dan cubaan semula

Baca respons ralat dan pengepala had kadar, cuba semula dengan selamat dan diagnosis kegagalan biasa.

Setiap Felo API mengembalikan badan ralat JSON dengan kod ralat yang stabil dan ID permintaan. Baca status HTTP dahulu, kemudian kod, kemudian mesej.

Sampul ralat

Respons pengeluaran semasa menggunakan status HTTP sebagai status:

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

Medan	Maksud
`status`	Kod status HTTP, diulang dalam badan
`code`	Kod ralat boleh dibaca mesin
`message`	Penjelasan boleh dibaca manusia
`request_id`	Pengecam legap untuk permintaan ini; sertakannya dalam permintaan sokongan

Beberapa contoh endpoint lama menggunakan status: "error" dan rentetan kod yang berbeza. Cabang berdasarkan status HTTP dan code, bukan pada perkataan tepat message.

Kod biasa

HTTP	Kod	Maksudnya	Apa yang perlu dilakukan
400	Kod pengesahan khusus endpoint	Parameter hilang atau tidak sah	Betulkan permintaan; jangan cuba semula tanpa perubahan
401	`UNAUTHORIZED`	Kunci API hilang, tidak sah, tamat tempoh, atau dibatalkan	Hantar `Authorization: Bearer $FELO_API_KEY`; putar kunci jika dibatalkan
402	`INSUFFICIENT_CREDITS`	Kredit perkhidmatan tidak mencukupi	Tambah nilai dalam Console Billing, kemudian cuba semula
404	Khusus endpoint	Model, tugasan, atau laluan tidak diketahui	Semak ID model atau ID tugasan dan laluan endpoint
429	`RATE_LIMITED`	Had kadar telah dilampaui	Tunggu `Retry-After`, kemudian cuba semula
5xx	`CHAT_FAILED`, `*_FAILED`, `SERVICE_UNAVAILABLE`	Kegagalan huluan atau perkhidmatan	Cuba semula dengan backoff; hubungi sokongan jika berterusan

Rujukan endpoint menyenaraikan kod khusus untuk endpoint tersebut. Mulakan dengan ralat Chat API atau rujukan untuk endpoint yang anda panggil.

Endpoint penjanaan model

POST /api/v1/images/generations dan POST /api/v1/videos/generations mengembalikan ralat peringkat endpoint dalam sampul OpenAI dan bukannya sampul 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 dalam pengepala respons X-Request-Id, bukan dalam badan. Permintaan yang ditolak tidak mencipta tugasan. Sebaik sahaja tugasan wujud, kebanyakan kegagalan tiba sebagai status tugasan terminal dalam respons 200 dan bukannya ralat HTTP: semak status untuk failed atau interrupted, kemudian baca error.message. Lihat Penjanaan Imej dan Tugasan Tak Segerak.

ID permintaan

Badan ralat Felo termasuk request_id. Log ia bersama endpoint, status HTTP, kod ralat, ID model, dan ID tugasan. Jangan sekali-kali log kunci API penuh.

Model API juga menerima pengepala permintaan X-Request-Id pilihan. Apabila anda menghantarnya, ia dipantulkan semula untuk diagnostik, yang membolehkan anda mengaitkan log anda sendiri dengan permintaan. Jika anda tidak menghantarnya, gunakan request_id yang dikembalikan.

Had kadar

/v2/chat ialah satu-satunya endpoint Felo dengan had kadar dikuatkuasakan yang didokumentasikan:

Setiap kunci API, tetingkap 1 minit.
Setiap pengguna, tetingkap 1 minit.
Setiap pengguna, tetingkap 1 jam.

Pengguna dengan langganan Felo berbayar yang berkesan, termasuk langganan perusahaan, dikecualikan dan tidak menerima pengepala X-RateLimit-*. Jika status langganan tidak dapat disahkan, had masih terpakai.

Pengepala	Maksud
`X-RateLimit-Limit`	Had dimensi paling ketat yang sedang berkuat kuasa
`X-RateLimit-Remaining`	Kuota baki minimum merentas tiga dimensi
`X-RateLimit-Reset`	Cap masa Unix dalam saat apabila tetingkap semasa ditetapkan semula
`Retry-After`	Pada 429, kelewatan yang disyorkan dalam saat

Endpoint /v2/** lain pada masa ini tiada had kadar yang dikuatkuasakan. Permintaan Model API masih boleh dihadkan oleh penyedia huluan, yang boleh muncul sebagai 429.

Jangan hardcode had berangka. Baca pengepala pada setiap respons.

Dasar cubaan semula

Keadaan	Cuba semula?
400, 401, 402, 404	Tidak. Betulkan permintaan, kunci, atau baki terlebih dahulu.
429	Ya, selepas `Retry-After` atau `X-RateLimit-Reset`.
5xx, tamat masa, set semula sambungan	Ya, dengan backoff eksponen dan jitter.
Sambungan penstriman terputus di tengah respons	Cuba semula hanya jika aplikasi anda boleh menerima penjanaan pendua.

Gelung yang disyorkan:

Cuba semula hanya permintaan idempoten atau selamat diulang.
Gunakan backoff eksponen: mulakan sekitar 1 saat, gandakan, hadkan pada 30 saat.
Tambahkan jitter rawak supaya klien tidak mencuba semula serentak.
Berhenti selepas bilangan percubaan yang kecil dan dedahkan ralat.
Pada 429, hormati Retry-After dan bukannya jadual anda sendiri.

Urutan nyahpepijat

Semak bahawa kunci wujud dan tidak dibatalkan.
Panggil GET /api/v1/models dengan kunci yang sama untuk mengesahkan pengesahan.
Hantar permintaan sah terkecil ke endpoint sasaran.
Tambahkan penstriman, alat, atau input besar satu demi satu.
Untuk kerja tak segerak, semak status tugasan sebelum menghantar semula.