Request dan error

Base URL dan format

Semua endpoint berada di bawah https://api.sealreply.com/v1. Kirim dan terima JSON (Content-Type: application/json). Waktu memakai format ISO 8601 dalam UTC. ID berupa UUID; ID pesan terurut berdasarkan waktu.

Setiap respons berupa amplop:

{ "success": true, "data": { … }, "error": null }

Error

Saat gagal, success bernilai false, data bernilai null, dan error menjelaskan penyebabnya:

{
  "success": false,
  "data": null,
  "error": {
    "code": "validation_failed",
    "message": "Some fields are invalid. Please check and try again.",
    "fields": { "email": "invalid" },
    "request_id": "req_01a1…"
  }
}

Buat program Anda berdasarkan code; message ditujukan untuk manusia dan mengikuti header Accept-Language. Sertakan request_id saat Anda menghubungi dukungan.

Kode	Status	Arti
bad_request	400	Request tidak bisa dibaca.
validation_failed	422	Ada field yang tidak valid; fields menyebutkan field tersebut dan alasannya.
unauthorized	401	Kunci tidak ada, tidak dikenal, atau sudah dicabut.
forbidden	403	Kunci tidak memiliki scope yang diperlukan (fields.scope), atau endpoint tidak terbuka untuk kunci.
tenant_suspended	403	Ruang kerja sedang ditangguhkan.
not_found	404	Resource tersebut tidak ada di ruang kerja Anda.
conflict	409	Sudah diubah sementara itu, atau Idempotency-Key yang sama masih sedang diproses.
conversation_closed	409	Percakapan sudah berakhir.
rate_limited	429	Terlalu banyak request; tunggu Retry-After detik.
quota_exceeded	402	Batas paket tercapai; fields.limit menyebutkan yang mana.
plan_upgrade_required	402	Paket Anda tidak menyertakan fitur ini; fields.feature menyebutkan yang mana.
internal	500	Kesalahan di pihak kami. Aman untuk dicoba ulang.

Paginasi

Daftar mengembalikan hingga limit item (bawaan 20, maksimal 100) dan sebuah cursor:

{ "data": [ … ], "meta": { "has_more": true, "next_cursor": "MjAyNi0…" } }

Kirim cursor=<next_cursor> untuk halaman berikutnya sampai has_more bernilai false. Daftar percakapan diurutkan dari aktivitas terbaru; riwayat pesan dipaginasi mundur dari yang terbaru.

Mencoba ulang dengan aman

• Pesan: beri setiap pesan client_msg_id yang Anda buat sendiri (sebuah UUID). Mengirim lagi dengan ID yang sama mengembalikan pesan pertama, bukan duplikat.
• Operasi tulis apa pun: kirim header Idempotency-Key (maksimal 255 karakter). Selama 24 jam, mengulang request yang sama mengembalikan respons sukses pertama dengan Idempotent-Replayed: true. Memakai ulang kunci untuk body yang berbeda mengembalikan 422 dengan fields.Idempotency-Key = reused; mengulang saat request pertama masih berjalan mengembalikan 409 conflict. Respons gagal tidak disimpan, jadi Anda bisa mencobanya ulang.

Field yang tidak dikenal

Respons dan body webhook bisa mendapat field baru dan nilai enum baru seiring waktu. Abaikan yang tidak Anda kenal, jangan sampai program gagal karenanya.