Lewati ke konten
bona fidedocs

Batas laju & idempotensi

Idempotensi

Section titled “Idempotensi”

Kirim header Idempotency-Key pada POST agar aman untuk dicoba ulang. Gunakan nilai baru yang unik per operasi (UUID, atau id dari sistem Anda sendiri seperti onboarding-8841): 1 hingga 255 karakter ASCII yang dapat dicetak.

Terminal window
curl https://api.bonafidesign.com/v1/envelopes \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2f0e-1d0b-4c2a-9a59-3f1f1c7d2b11" \
  -d @envelope.json
  • Permintaan pertama dengan suatu kunci berjalan normal dan responsnya disimpan selama 24 jam.
  • Percobaan ulang dengan kunci yang sama dan permintaan yang sama (metode, path, query, dan body) mendapat respons tersimpan yang diputar ulang, dengan header Idempotent-Replayed: true.
  • Kunci yang sama dengan permintaan yang berbeda menghasilkan 422 idempotency-key-reused.
  • Percobaan ulang saat permintaan pertama masih berjalan menghasilkan 409 idempotency-in-progress; coba lagi beberapa saat kemudian.
  • Respons 5xx tidak disimpan, sehingga percobaan ulang setelah error server akan dijalankan lagi.

Kunci dibatasi pada pemanggilnya: organisasi dan kunci API (atau pengguna dasbor) yang mengirimkannya. Operasi yang menerima kunci ditandai dengan parameter header Idempotency-Key di referensi API, di antaranya membuat template, mengunggah file, memublikasikan, membuat dan membatalkan amplop, mengirim ulang tautan, membuat sesi penandatanganan, membuat tautan penandatanganan dan endpoint webhook, serta mengirim ulang event.

Deduplikasi berdasarkan id Anda sendiri

Section titled “Deduplikasi berdasarkan id Anda sendiri”

Kunci idempotensi melindungi percobaan ulang dari satu permintaan. Untuk memastikan sebuah objek bisnis hanya pernah dikirim sekali, kirim juga id Anda sendiri dan dedupeOn:

{ "template": "tpl_…", "externalId": "user_8841", "dedupeOn": "external_id", "…": "…" }

Jika amplop dengan externalId tersebut sudah ada (dalam mode yang sama), POST /v1/envelopes mengembalikannya dengan 200 dan x-deduplicated: true alih-alih membuat amplop baru. Ini berlaku lintas kunci, lintas hari, dan untuk permintaan bersamaan.

Batas laju

Section titled “Batas laju”

API terautentikasi (kunci API) saat ini tidak memiliki batas laju permintaan yang tetap; pengiriman dibatasi oleh paket Anda. Batas berlaku di tempat yang rawan penyalahgunaan:

Lokasi Batas
POST /v1/public/verify 60 permintaan per menit per IP
GET /v1/public/anchors…, /.well-known/bona-fide/* 240 permintaan per menit per IP
GET /v1/sso/discover 30 pencarian per menit per IP
Kode sekali pakai penanda tangan 5 kode per 15 menit per sesi; 5 percobaan per kode
Pengiriman ulang ke penerima Sekali per menit per penerima
Tautan yang selalu aktif Per tautan: perEmailPerDay (default 3), perIpPerHour (default 20), opsional dailyCap
Masuk ke dasbor dengan kata sandi 10 per menit per IP; 10 per 15 menit per alamat email
Pendaftaran dasbor dengan kata sandi 5 per menit per IP; 5 per jam per alamat email
Email reset kata sandi 5 per 15 menit per IP; 3 per jam per alamat email
Kode masuk dasbor 3 per menit per IP

Endpoint publik yang dibatasi mengirim header RateLimit-Limit, RateLimit-Remaining, dan RateLimit-Reset (detik). Jika batas terlampaui, API menjawab 429 dengan problem rate-limited, biasanya disertai header Retry-After dalam detik.