Basis pengetahuan GetMyBot

Kesalahan API

Pahami alasan permintaan gagal, kapan harus memperbaikinya, dan cara mengulang pembayaran atau siaran tanpa membuat tindakan ganda.

Di halaman ini

Jika permintaan gagal, lihat kode HTTP terlebih dahulu. Misalnya, 401 menunjukkan masalah akses dan 429 berarti permintaan terlalu sering. Teks pada kolom error menjelaskan alasannya. Jika berhasil, respons langsung berisi data tanpa pembungkus tambahan.

Bentuk respons kesalahan

Saat terjadi kesalahan, server mengirim objek JSON dengan kolom error:

{"error":"reaction not found"}

Gunakan kode HTTP untuk menentukan tindakan berikutnya. Teks error berguna untuk catatan teknis dan penjelasan kepada pengguna.

Kode status

Kode HTTPArtinya
200 OKPermintaan berhasil dan respons berisi data.
201 CreatedData baru berhasil dibuat, pada sebagian permintaan POST.
204 No ContentBerhasil tanpa isi respons, pada sebagian penghapusan.
400 Bad RequestIsi atau parameter permintaan salah.
401 UnauthorizedToken tidak ada, salah, atau kedaluwarsa; atau alamat ini tidak menerima token pribadi.
402 Payment RequiredPaket atau kuota tidak mengizinkan tindakan, misalnya penyimpanan media pribadi memerlukan paket premium.
403 ForbiddenToken tidak memiliki cakupan akses yang dibutuhkan, atau pemilik token tidak memiliki hak atas ruang kerja. Lihat Ruang kerja token.
404 Not FoundData tidak ditemukan atau tidak dapat diakses oleh Anda.
409 ConflictAda konflik, misalnya nilai unik sudah dipakai. Untuk permintaan dengan Idempotency-Key, ini juga dapat berarti tindakan yang sama masih berjalan.
413 Payload Too LargeData yang dikirim terlalu besar. Lihat batas ukuran. Permintaan dengan Idempotency-Key memiliki batas khusus 64 KiB.
422 Unprocessable EntityBentuk data benar, tetapi isinya tidak lolos pemeriksaan. Untuk Idempotency-Key, ini juga berarti kunci yang sama dipakai dengan isi berbeda.
429 Too Many RequestsPermintaan dikirim terlalu sering. Lihat batas frekuensi.
500 Internal Server ErrorTerjadi kesalahan server; coba lagi nanti.

Cara menanggapi kesalahan

Kode 2xx berarti berhasil. Untuk 401 atau 403, periksa token, cakupan akses, dan hak Anda di ruang kerja. Untuk 429 dan 5xx, tunggu sebelum mengulang, lalu tambah waktu tunggu jika masih gagal.

Untuk kode 4xx selain 429, biasanya Anda perlu memperbaiki permintaan sebelum mengulang. Ada satu pengecualian: 409 pada permintaan dengan Idempotency-Key dapat berarti tindakan yang sama sedang berjalan. Jangan anggap pembayaran atau siaran gagal. Tunggu sesuai Retry-After, lalu ulangi dengan kunci yang sama.

Mengulang pembayaran dan siaran dengan Idempotency-Key

Kunci harus berupa UUID standar dengan huruf kecil dan tanda hubung, misalnya 9b1f0d4c-2f6a-4a5f-9a3f-1f2f3a4b5c6d. Bentuk lain ditolak dengan 400.

Di mana kunci digunakan?

Header ini boleh diisi pada tindakan yang dapat menimbulkan biaya atau mengirim banyak pesan:

  • POST /api/billing/topup: mengisi saldo;
  • POST /api/billing/subscribe: berlangganan;
  • POST /api/bots/{botID}/reactions/{reactionID}/broadcast: menjalankan siaran.

Untuk dua tindakan pengiriman oleh operator berikut, header ini wajib; tanpa kunci, permintaan ditolak dengan 400:

  • POST /api/bots/{botID}/users/{userID}/dialog/messages;
  • POST /api/bots/{botID}/support/dialogs/{subscriberID}/templates.

Alamat API lain mengabaikan header tersebut. Jadi, kunci ini tidak mencegah pengulangan di semua alamat.

Respons server

  • Kunci dan isi sama, tindakan sudah selesai: server mengembalikan respons yang disimpan dari percobaan pertama, dengan kode dan isi yang sama serta header Idempotent-Replay: true. Catatan ini disimpan selama satu minggu.
  • Kunci sama, tindakan masih berjalan: server mengirim 409 dan Retry-After. Tunggu sesuai waktu tersebut, lalu ulangi dengan kunci yang sama. Kunci baru dapat membuat tindakan kedua.
  • Kunci sama, isi berbeda: server mengirim 422. Gunakan kunci baru untuk tindakan yang memang berbeda.
  • Isi lebih besar dari 64 KiB: server mengirim 413.

Server tidak menyimpan respons 5xx, 408, 425, dan 429 sebagai hasil akhir kunci. Karena itu, Anda dapat mengulang dengan kunci yang sama setelah respons tersebut.

Langkah penggunaan

  1. Buat UUID sebelum permintaan pertama dan simpan bersama data tindakan.
  2. Kirim permintaan dengan UUID tersebut sebagai Idempotency-Key.
  3. Jika sambungan terputus, waktu tunggu habis, atau menerima 5xx atau 429, ulangi dengan kunci yang sama.
  4. Jika menerima 409, tunggu sesuai Retry-After dan ulangi dengan kunci yang sama.
  5. Buat kunci baru hanya untuk tindakan baru.

Jangan membuat kunci baru pada setiap percobaan. Jika dilakukan, server akan menganggap setiap percobaan sebagai tindakan berbeda dan perlindungan terhadap tindakan ganda tidak berlaku.

Kesalahan AI dan pengaturan alur

Managed AI dapat mengembalikan alasan not_available (fitur tidak tersedia), not_entitled (akses tidak ada), budget_exceeded (anggaran habis), rate_limited (terlalu sering), provider_unavailable (layanan model tidak tersedia), atau schema_validation_failed (bentuk respons tidak lolos pemeriksaan). Ulangi hanya jika respons mengizinkannya, dengan Idempotency-Key yang sama. Untuk kesalahan 4xx selain 429 atau kesalahan pemeriksaan bentuk data, perbaiki permintaan. Mengganti penyedia model tidak menyelesaikan masalah bentuk data.

Jika Copilot mengembalikan stale_base, saran perubahan reaksi sudah kedaluwarsa; buat ulang berdasarkan reaksi saat ini. Perubahan aturan analisis mengembalikan 409 jika permintaan lain sudah mengubah aturan tersebut. Penghitungan ulang analitik dan pemutaran ulang langkah berjalan sebagai tugas terbatas. Periksa status tugas yang sudah dimulai sebelum membuat tugas baru. Pemeriksaan koneksi Meta mengembalikan kode alasan untuk membantu mencari masalah, tanpa menyertakan token akses atau seluruh respons Meta.

Langkah berikutnya