Error & batasan

Format error

Semua error punya bentuk yang sama, dan code stabil antar rilis. Bercabanglah berdasarkan code, bukan teks pesannya.

{
  "error": {
    "code": "APPROVAL_REQUIRED",
    "message": "This action needs your approval.",
    "requestId": "req-8f2c…",
    "details": { "approvalId": "…" }
  }
}

message aman ditampilkan ke pengguna. Sertakan requestId saat menghubungi support.

Kode	HTTP	Arti
UNAUTHENTICATED	401	Tidak ada sesi yang valid. Login ulang.
FORBIDDEN	403	Sudah login, tapi tidak diizinkan (peran, workspace, atau header client tidak ada).
POLICY_DENIED	403	Kebijakan workspace memblokir tool atau connector ini.
NOT_FOUND	404	Tidak ada, atau bukan milik Anda.
VALIDATION_FAILED	400	Request tidak valid. details.issues merinci tiap field.
CONFLICT	409	Bentrok dengan data yang ada (misalnya slug sudah dipakai).
INVALID_STATE	409	Tidak bisa dilakukan saat ini (misalnya membatalkan run yang sudah selesai).
CONNECTION_REQUIRED	409	Hubungkan akunnya dulu. details.toolkitSlug menyebut yang mana.
APPROVAL_REQUIRED	409	Perlu persetujuan. details.approvalId menunjuk approval-nya.
IDEMPOTENCY_CONFLICT	409	Idempotency key dipakai ulang dengan input berbeda.
RATE_LIMITED	429	Terlalu banyak request. Tunggu sebentar lalu coba lagi.
UPSTREAM_FAILED	502	Penyedia model atau integrasi mengembalikan error.
INTEGRATION_UNAVAILABLE	503	Penyedia integrasi tidak tersedia.
UPSTREAM_TIMEOUT	504	Penyedia tidak menjawab tepat waktu.
INTERNAL_ERROR	500	Ada masalah di sisi kami.

Error validasi merinci setiap masalah:

{ "error": { "code": "VALIDATION_FAILED", "message": "Request validation failed.",
  "details": { "issues": [{ "path": "name", "message": "Too small: expected string to have >=1 characters" }] } } }

Batasan

Batasan	Nilai
Login dan register (/auth/*)	20 request per menit
Semua endpoint lain	600 request per menit
Body request	15 MB (cukup untuk lampiran 10 MB dalam base64)
Panjang pesan	20.000 karakter
Lampiran	5 per pesan, masing-masing 10 MB
Streaming run	Satu stream terbuka paling lama 30 menit; sambungkan ulang untuk melanjutkan
Pemakaian model dan tool	Kuota token bulanan sesuai paket workspace; run berhenti dengan RATE_LIMITED saat kuota habis

Paginasi

Daftar yang bisa bertambah panjang menerima limit (1–100, bawaan 50) dan cursor, dan mengembalikan:

{ "items": [ … ], "nextCursor": "50" }

Kirim nextCursor sebagai cursor pada request berikutnya sampai nilainya null.

Idempotensi

Eksekusi tool (POST /integrations/tools/{toolSlug}/execute) menerima idempotencyKey (8–200 karakter). Mengulang request dengan key dan input yang sama mengembalikan "status": "duplicate" alih-alih menjalankan tool dua kali; key yang sama dengan input berbeda gagal dengan IDEMPOTENCY_CONFLICT.