Idempotency
Retry batches and reconciles safely with Idempotency-Key; PUT is safe to repeat on its own; redeem has no key.
Idempotency-Key#
POST /connections/{id}/batches and POST /connections/{id}/reconcile honour an Idempotency-Key header. Use one key per distinct request, and the same key when you retry that request. A key is 8–128 visible ASCII characters, no spaces; anything else is 422 validation_failed (pointer "", code invalid_format).
| You send | We answer |
|---|---|
| the same key and the same body, after the first request finished | the stored outcome, rebuilt from the batch and its items, with the header Idempotent-Replayed: true |
| the same key while the first request is still running | 409 idempotency_in_progress with details: { "batch_id": "…" } — poll GET /batches/{id} |
| the same key with a different body | 422 idempotency_key_reused |
| a key older than 7 days | a new request (keys are forgotten after 7 days) |
POST /api/partners/v1/connections/9b1d6c2e-4f3a-4c8e-9a71-2d5e8f0b3c44/batches
Idempotency-Key: 2026-10-12T08:00-agency-17A push we refuse before it starts (for example 429 connection_item_limit, or a reconcile refused by the mass-removal guard) leaves the key free for your retry.
PUT is safe to repeat#
PUT /connections/{id}/listings/{external_id} takes no key: it fully replaces the listing, and a repeat with the same content answers unchanged (same digest, nothing queued). Repeat it as often as you like.
Redeem has none#
POST /connections (redeem a code) takes no key. A code works once: a retry after a success answers 404 connect_code_invalid, and GET /connections shows the connection the first call created.
Last updated