Error API

Halaman ini memberikan referensi untuk semua kode error Interactions API, menjelaskan format respons error, dan menjelaskan cara API menyampaikan error untuk berbagai jenis permintaan.

Kode error API standar

Kode error tingkat permintaan umum ini sesuai dengan kode status HTTP standar. Gunakan kolom code dalam logika aplikasi Anda untuk menangani error secara terprogram.

Kode Status HTTP Deskripsi Tindakan yang disarankan
invalid_request 400 Bad Request (400 Permintaan Tidak Valid) Payload permintaan salah format atau berisi parameter yang tidak valid. Periksa sintaksis dan parameter permintaan Anda berdasarkan referensi API.
failed_precondition 400 Bad Request (400 Permintaan Tidak Valid) Permintaan tidak dapat diproses karena prasyarat tidak terpenuhi (misalnya, penagihan dinonaktifkan). Verifikasi status penagihan project atau prasyarat akun.
out_of_range 416 Requested Range Not Satisfiable Parameter permintaan berada di luar rentang yang valid. Periksa nilai dan batas parameter.
parameter_unknown 400 Bad Request (400 Permintaan Tidak Valid) Permintaan berisi parameter yang tidak diketahui. Hapus parameter yang tidak dikenal, lalu coba lagi.
authentication 401 Tidak Sah Kunci API tidak ada, tidak valid, atau sudah tidak berlaku. Verifikasi kunci API Anda.
payment_required 402 Pembayaran Diperlukan Saldo kredit Prabayar Anda habis. Tambahkan kredit ke akun penagihan Anda, atau aktifkan isi ulang otomatis. Jangan coba lagi: permintaan tidak akan berhasil hingga kredit ditambahkan.
permission_denied 403 Terlarang Kunci API Anda tidak memiliki izin untuk resource ini. Periksa izin kunci API dan akses project Anda.
not_found 404 Tidak Ditemukan Resource yang diminta tidak ditemukan. Verifikasi jalur dan parameter resource.
model_not_found 404 Tidak Ditemukan Model yang ditentukan tidak ditemukan. Verifikasi nama model atau beralih ke model lain.
already_exists 409 Conflict Entity yang Anda coba buat sudah ada. Periksa apakah resource sudah ada sebelum membuatnya ulang.
aborted 409 Conflict Operasi dibatalkan karena konflik atau kegagalan pemeriksaan konkurensi. Coba lagi permintaan di tingkat aplikasi yang lebih tinggi.
rate_limit_exceeded 429 Too Many Requests Anda telah melampaui batas permintaan atau token per menit atau per detik. Tunggu dan coba lagi dengan backoff eksponensial.
quota_exceeded 429 Too Many Requests Anda telah melampaui kuota harian. Tunggu hingga kuota direset atau minta penambahan kuota.
too_many_requests 429 Too Many Requests Anda telah membuat terlalu banyak permintaan dalam waktu singkat. Tunggu dan coba lagi dengan backoff eksponensial.
cancelled 499 Client Closed Request Klien membatalkan permintaan sebelum selesai. Tidak perlu tindakan apa pun. Hal ini biasanya berarti klien terputus.
api_error 500 Error Server Internal Terjadi error tak terduga di server. Coba lagi permintaan tersebut. Jika masalah berlanjut, hubungi dukungan.
unimplemented 501 Not Implemented Operasi atau fitur tidak diterapkan atau didukung. Periksa kemampuan API atau beralih ke fitur yang didukung.
service_unavailable 503 Layanan Tidak Tersedia Layanan sedang kelebihan beban atau tidak berfungsi untuk sementara. Tunggu dan coba lagi dengan backoff eksponensial.
deadline_exceeded 504 Waktu Tunggu Gateway Permintaan tidak selesai dalam batas waktu. Hapus atau tingkatkan setelan batas waktu klien untuk menggunakan default server.

Kode yang diblokir pembuatan

Kode error ini menunjukkan bahwa pembatasan kebijakan, keamanan, atau konten memblokir output model. Saat Anda menerima salah satu kode ini, ubah input Anda dan coba lagi.

Kode Deskripsi
safety Pelanggaran keamanan (konten berbahaya) memblokir permintaan.
recitation Pembatasan hak cipta atau pembacaan memblokir permintaan.
language Bahasa yang tidak didukung memblokir permintaan.
prohibited_content Pedoman konten terlarang memblokir permintaan.
spii Pembatasan Informasi Identitas Pribadi yang Bersifat Sensitif memblokir permintaan.
blocklist Istilah terlarang dalam daftar blokir memblokir permintaan.
image_safety Pelanggaran keamanan memblokir pembuatan gambar.
image_prohibited_content Pedoman konten terlarang memblokir pembuatan gambar.
image_recitation Pembatasan hak cipta atau pembacaan memblokir pembuatan gambar.
image_other Alasan yang tidak ditentukan memblokir pembuatan gambar.
content_blocked Permintaan diblokir karena alasan kebijakan yang tidak ditentukan.

Kode error pembuatan

Kode error ini menunjukkan masalah struktural pada output yang dihasilkan model (seperti panggilan fungsi yang salah bentuk atau panggilan alat yang tidak dideklarasikan).

Kode Deskripsi
malformed_function_call Model menghasilkan panggilan fungsi yang tidak dapat diuraikan.
malformed_tool_call Model menghasilkan panggilan alat yang tidak dapat diuraikan.
unexpected_tool_call Model memanggil alat yang tidak dideklarasikan dalam permintaan.
no_image Model tidak dapat membuat gambar.
too_many_tool_calls Model menghasilkan lebih banyak panggilan alat daripada yang diizinkan.
missing_thought_signature Respons tidak memiliki tanda tangan pemikiran yang diperlukan.

Format respons error

Semua error dari Interactions API menampilkan objek error yang berisi code dan message. Misalnya, meneruskan jenis alat yang tidak didukung akan menampilkan:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."
  }
}
Kolom Jenis Deskripsi
code string Kode error yang dapat dibaca mesin dalam snake_case.
message string Deskripsi yang dapat dibaca manusia tentang kesalahan yang terjadi.

Cara error dikirimkan

API memberikan error secara berbeda, bergantung pada apakah Anda membuat permintaan HTTP standar atau permintaan streaming (SSE).

Permintaan HTTP standar

Untuk permintaan standar (non-streaming), API menetapkan kode status respons HTTP (seperti 400 Bad Request, 401 Unauthorized, atau 429 Too Many Requests) dan menampilkan objek error dalam isi respons JSON:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."
  }
}

Permintaan streaming (SSE)

Untuk permintaan streaming (stream: true), API mengirim peristiwa error melalui aliran Server-Sent Events (SSE) dengan event_type disetel ke "error". Kolom error berisi struktur code dan message yang sama:

{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}

Untuk skema peristiwa SSE lengkap, lihat Referensi Interactions API.

Langkah berikutnya