Error API

Halaman ini menyediakan referensi untuk semua kode error Interactions API, menjelaskan format respons error, dan menjelaskan cara API mengirimkan 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 Permintaan Buruk Payload permintaan salah format atau berisi parameter yang tidak valid. Periksa sintaksis dan parameter permintaan Anda berdasarkan referensi API.
failed_precondition 400 Permintaan Buruk Permintaan tidak dapat diproses karena prasyarat tidak terpenuhi (misalnya, penagihan dinonaktifkan). Verifikasi status penagihan project atau prasyarat akun.
out_of_range 416 Rentang yang Diminta Tidak Dapat Dipenuhi Parameter permintaan berada di luar rentang yang valid. Periksa nilai dan batas parameter.
parameter_unknown 400 Permintaan Buruk Permintaan berisi parameter yang tidak dikenal. Hapus parameter yang tidak dikenal dan coba lagi.
authentication 401 Tidak Sah Kunci API tidak ada, tidak valid, atau sudah tidak berlaku. Verifikasi kunci API Anda.
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 gunakan model lain.
already_exists 409 Conflict Entity yang Anda coba buat sudah ada. Periksa apakah resource sudah ada sebelum dibuat 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 Terlalu Banyak Permintaan Anda telah melampaui batas permintaan atau token per menit atau per detik. Tunggu dan coba lagi dengan backoff eksponensial.
quota_exceeded 429 Terlalu Banyak Permintaan Anda telah melampaui kuota harian. Tunggu hingga kuota direset atau minta penambahan kuota.
too_many_requests 429 Terlalu Banyak Permintaan Anda telah membuat terlalu banyak permintaan dalam waktu singkat. Tunggu dan coba lagi dengan backoff eksponensial.
cancelled 499 Klien Menutup Permintaan Klien membatalkan permintaan sebelum selesai. Tidak perlu tindakan apa pun. Biasanya ini berarti klien terputus.
api_error 500 Error Server Internal Terjadi error yang tidak terduga di server. Coba lagi permintaan tersebut. Jika masalah berlanjut, hubungi dukungan.
unimplemented 501 Tidak Diterapkan Operasi atau fitur tidak diterapkan atau tidak didukung. Periksa kemampuan API atau beralih ke fitur yang didukung.
service_unavailable 503 Layanan Tidak Tersedia Layanan sedang kelebihan beban atau tidak tersedia 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 memblokir pembuatan

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

Kode Deskripsi
safety Pelanggaran keamanan (konten berbahaya) memblokir permintaan.
recitation Pembatasan hak cipta atau kutipan 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 kutipan memblokir pembuatan gambar.
image_other Alasan yang tidak ditentukan memblokir pembuatan gambar.
content_blocked Alasan kebijakan yang tidak ditentukan memblokir permintaan.

Kode error pembuatan

Kode error ini menunjukkan masalah struktural dengan output yang dihasilkan model (seperti panggilan fungsi yang salah format 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 apa yang salah.

Cara error dikirimkan

API mengirimkan 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 mengirimkan peristiwa error melalui aliran Server-Sent Events (SSE) dengan event_type ditetapkan 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 mengetahui skema peristiwa SSE lengkap, lihat Referensi Interactions API.

Langkah berikutnya