fingerlydocs
fingerly.io Log inDashboard
API reference

Idempotency and retries

Retry an identification safely: the Idempotency-Key header makes a repeated request return the first answer, charged once.

A network can fail after Fingerly has answered but before the answer reaches the client. Retrying then would identify the visitor twice and charge twice. An idempotency key prevents both.

Idempotency keys

Send a unique Idempotency-Key header with POST /identify, and send the same value with every retry of that request.

Request
POST /api/v1/identify HTTP/1.1
Host: us.api.fingerly.io
Content-Type: application/json
x-api-key: fly_pk_us_production_…
Idempotency-Key: 7d5e1f2a-3c4b-4d6e-8f90-a1b2c3d4e5f6
  • Keys are scoped to your organization and remembered for at least one hour.
  • Use a random UUID. Keys may be up to 255 characters.
  • A repeat of a key that was already answered returns 200 with the first request_id and "duplicate": true, is not charged, and does not count against your rate limit.
  • A request refused with 402 or 429 releases its key, so the retry is processed normally.
Duplicate response
{
  "request_id": "01a0a84b-e6a2-7c09-9f51-0b3d7a26c8e4",
  "duplicate": true
}

How the SDKs retry

SDKAttemptsRetries onBackoff
JavaScript and web frameworks3Network errors, timeouts, 408, 425, 429, 5xxFull jitter from 100 ms, capped at 2 s
iOS and Android3Network errors, 429, 5xxFull jitter from 100 ms, capped at 2 s

Every SDK attempt times out after 5 seconds and reuses one idempotency key per identify() call.

Other endpoints

  • GET requests are naturally safe to retry.
  • POST /events/{request_id}/supplement deduplicates on content: resending the same deferred report returns 202 with "duplicate": true, and a different one returns 409.

Last updated