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 Bad Request Permintaan salah format atau berisi parameter yang tidak valid. Periksa input Anda berdasarkan referensi API.
parameter_unknown 400 Bad Request Permintaan berisi parameter yang tidak dikenal. Hapus parameter yang tidak dikenal dan coba lagi.
authentication 401 Unauthorized Kunci API tidak ada atau tidak valid. Verifikasi kunci API Anda.
permission_denied 403 Forbidden Kunci API Anda tidak memiliki izin untuk resource ini. Periksa izin kunci API dan akses project Anda.
not_found 404 Not Found Resource yang diminta tidak ditemukan. Verifikasi jalur dan parameter resource.
model_not_found 404 Not Found Model yang ditentukan tidak ditemukan. Verifikasi nama model atau gunakan model lain.
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.
cancelled 499 Client Closed Request Klien membatalkan permintaan sebelum selesai. Tidak perlu tindakan apa pun. Biasanya, hal ini berarti klien terputus.
api_error 500 Internal Server Error Terjadi error yang tidak terduga di server. Coba lagi permintaan tersebut. Jika masalah berlanjut, hubungi dukungan.
service_unavailable 503 Service Unavailable Layanan untuk sementara kelebihan beban atau tidak berfungsi. Tunggu dan coba lagi dengan backoff eksponensial.

Kode yang memblokir pembuatan

Kode error ini menunjukkan bahwa batasan kebijakan, keamanan, atau 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 Batasan hak cipta atau kutipan memblokir permintaan.
language Bahasa yang tidak didukung memblokir permintaan.
prohibited_content Pedoman konten terlarang memblokir permintaan.
spii Batasan 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 Batasan 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 masalahnya.

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