Kode Kesalahan dan Pemecahan Masalah

Kenali Bagian yang Gagal

1. Catat status HTTP, metode permintaan, dan jalur yang sebenarnya. Status HTTP dan kode kesalahan aplikasi menjelaskan lapisan yang berbeda; jangan saling menggantikannya.
2. Baca kolom kesalahan sesuai protokol yang Anda panggil. Respons native, OpenAI, Claude, dan Gemini tidak semuanya memiliki struktur yang sama.
3. Untuk permintaan streaming, periksa juga peristiwa kesalahan dan status penyelesaiannya. Untuk tugas asinkron, periksa status tugas. HTTP 200 tidak menjamin pembuatan berhasil.
4. Gunakan tabel di bawah untuk memperbaiki permintaan atau memutuskan apakah perlu mencoba kembali. message adalah teks penjelasan, bukan enum yang stabil; jangan membuat percabangan berdasarkan kata-katanya.

Enum Kode Kesalahan Platform

Ini adalah enum lengkap kode kesalahan aplikasi platform. Nama merupakan label referensi; nilai code dalam respons berupa angka. “HTTP Umum” adalah panduan pemecahan masalah, bukan pemetaan tetap untuk setiap endpoint. Gunakan status HTTP dan isi respons yang sebenarnya. code yang diteruskan dari upstream mungkin tidak termasuk dalam enum ini.

HTTP 429 saja tidak dapat membedakan batas laju dan batas konkurensi secara andal. Bedakan keduanya hanya jika tersedia kode kesalahan numerik yang eksplisit. Periksa pengenal model dalam daftar model; jangan menulis ulang nilai model sendiri.

Baca Kesalahan Berdasarkan Protokol

Contoh di bawah menunjukkan struktur umum yang dihasilkan platform, bukan satu format yang dijamin untuk setiap kegagalan. Kegagalan autentikasi dapat dikembalikan oleh lapisan pemrosesan yang berbeda, dan respons yang diteruskan dari upstream dapat mempertahankan struktur, kode string, atau tipenya sendiri. Kenali bentuk respons yang sebenarnya sebelum menguraikannya. Jika tidak dikenali, simpan kolom asli dan status HTTP alih-alih memaksakan konversi.

API Native Platform

Biasanya baca error.code dan error.message. requestId mungkin tidak ada.

{
  "success": false,
  "error": {
    "code": 10000,
    "message": "Bad request"
  },
  "requestId": "req_example"
}

Sebagian kesalahan mungkin menggunakan code dan message tingkat atas. Klien harus menerima perbedaan ini dan tidak boleh menganggap ketiadaan objek error sebagai bukti keberhasilan. Respons validasi parameter juga mungkin tidak memiliki kode kesalahan numerik. Anggap kode yang tidak ada sebagai tidak diketahui, bukan mengarangnya.

API Kompatibel OpenAI

Kesalahan umum yang dihasilkan platform menggunakan code, message, dan type tingkat atas; kolom tersebut tidak selalu dibungkus dalam error.

{
  "code": 40000,
  "message": "Insufficient credit",
  "type": "api_error"
}

type adalah kategori protokol; code adalah kode kesalahan numerik platform dalam struktur ini. api_error saja tidak menentukan apakah percobaan ulang tepat dilakukan. Kesalahan upstream yang diteruskan dan kesalahan streaming dapat berisi error bertingkat; tangani respons protokol yang sebenarnya. Lihat Chat Completions dan Responses.

API Kompatibel Claude

Dalam struktur umum, type tingkat atas bernilai error, kategori spesifiknya adalah error.type, dan deskripsinya adalah error.message. Struktur ini tidak mencakup code numerik platform. Jangan mengarangnya.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens must be a positive safe integer"
  }
}

Platform menghasilkan tipe kesalahan Claude berikut secara lokal. Ini bukan enum lengkap tipe kesalahan upstream.

Lihat Claude Messages.

Kesalahan Bergaya Gemini

Saat menerima respons bergaya Gemini, baca error.code, error.message, dan error.status. Di sini, status adalah kategori string, bukan status HTTP atau status tugas asinkron.

{
  "error": {
    "code": 10000,
    "message": "Bad request",
    "status": "INVALID_ARGUMENT"
  }
}

Kesalahan yang dihasilkan platform dalam bentuk ini menggunakan nilai code numerik platform. Pemetaan string status lokal ada di bawah; ini bukan enum seluruh status upstream.

503 diprioritaskan dan menggunakan UNAVAILABLE, bukan INTERNAL. Respons upstream mungkin menggunakan semantik code dan status yang berbeda. Jangan menerapkan tabel kode kesalahan platform ke setiap kode numerik Gemini.

Mencoba Kembali dengan Aman

Patuhi header Retry-After yang valid jika tersedia. Jangan berasumsi setiap kesalahan menyertakannya. Mencoba ulang secara otomatis permintaan pembuatan yang tidak idempoten dapat mengeksekusinya lagi dan menimbulkan biaya tambahan. Halaman ini tidak menjanjikan dukungan umum kunci idempotensi; menambahkan Idempotency-Key sendiri tidak menjamin deduplikasi.

Jika Anda sudah memiliki jobId, periksa tugas tersebut sebelum membuat yang lain. Jika tidak memiliki jobId dan hasilnya belum pasti, simpan pengenal permintaan dan stempel waktu untuk investigasi.

Streaming dan Tugas Asinkron

Permintaan SSE

Setelah SSE dimulai, status HTTP mungkin tetap 200 sementara kegagalan berikutnya dilaporkan melalui peristiwa kesalahan atau payload dalam stream. Uraikan peristiwa dan data sesuai protokol yang dipilih dan periksa penyelesaian normal. Saat terjadi kesalahan atau koneksi terputus secara tak terduga, jangan menganggap teks atau gambar parsial sebagai hasil lengkap yang berhasil. Nama peristiwa dan payload berbeda antar-endpoint. Jangan hanya memeriksa satu kolom error tetap atau menggunakan “teks apa pun telah diterima” sebagai syarat keberhasilan.

Tugas Asinkron

Respons pembuatan yang berisi data.jobId berarti permintaan telah diterima, bukan pembuatan sudah selesai. Respons HTTP yang berhasil saat memeriksa tugas berarti kueri berhasil. Anda tetap harus memeriksa data.status tugas:

• PENDING, CONNECT, PROCESSING: lanjutkan polling sebagaimana dijelaskan dalam dokumentasi Jobs.
• COMPLETED: baca outputResult.
• FAILED, CANCELLED: hentikan polling dan simpan ID tugas serta informasi respons yang telah dibersihkan dari data sensitif untuk investigasi.

Detail kegagalan mungkin muncul dalam data.outputResult.error. Kolom ini opsional dan tidak dijamin ada untuk setiap tugas yang gagal. Gunakan Jobs hanya jika respons pembuatan secara eksplisit mengembalikan jobId. Jangan menerapkan polling tugas ke endpoint yang mengembalikan hasil langsung melalui JSON atau SSE.

Diagnostik untuk Pengguna dan Asisten AI

Berikan informasi berikut yang telah dibersihkan dari data sensitif kepada dukungan atau asisten AI. Gunakan unknown untuk kolom yang tidak ada; gunakan unknown untuk status HTTP jika tidak menerima respons HTTP. Pertahankan jalur kolom dan tipe nilai asli, misalnya error.code: 10000 (number) atau error.code: "invalid_api_key" (string). Jangan otomatis mengonversi code string menjadi kode numerik platform atau mengarang kolom yang tidak ada berdasarkan message, status HTTP, atau nama model.

time_with_timezone: unknown
method: unknown
path_without_query: unknown
model: unknown
stream: unknown
http_status: unknown
error_code_path_value_and_type: unknown
error_type_path_and_value: unknown
protocol_status_path_and_value: unknown
sanitized_message: unknown
request_id_from_body_or_X-Request-ID: unknown
job_id: unknown
job_status: unknown
retry_after: unknown
retry_count_and_delays: unknown
received_partial_output: unknown

Baca requestId dari isi respons atau header respons X-Request-ID jika tersedia. Pertahankan jobId sebagai string agar angka panjang tidak kehilangan presisi. Berikan hanya parameter permintaan minimal yang telah dibersihkan dari data sensitif. Hapus API Key, token, cookie, header autentikasi lengkap, informasi pribadi, prompt privat, dan isi file masukan. Hapus parameter kueri URL serta URL masukan atau keluaran yang berisi tanda tangan atau kredensial akses. Jangan menempelkan log permintaan lengkap tanpa meninjaunya.

Asisten AI harus membedakan kolom yang diamati dari kemungkinan penyebab dan mengidentifikasi informasi yang belum tersedia. Bukti yang tidak cukup tidak boleh dianggap sebagai bukti bahwa permintaan berhasil, tidak dieksekusi, atau tidak dikenai biaya.