Idempotency and retries

Retries are safest when the endpoint contract explicitly describes idempotency. A timeout does not tell you whether the server completed a request, so inspect the resource or job before repeating a side effect.

Read operations

GET requests are safe to retry. Preserve the same authentication, filters, and pagination cursor.

Resource creation

Send an Idempotency-Key header on any POST, PUT, PATCH or DELETE. Reuse one value for retries of one logical action and generate a new value for a genuinely new action. Requests without the header are processed normally and are not deduplicated.

curl -X POST "https://api.sendora.ai/api/v1/public/leads" \
  -H "X-API-Key: $SENDORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lead-import-2026-09-20-001" \
  -d '{"email":"jane@example.com","first_name":"Jane"}'

Situation	Result
Same key, same body, first request finished	The stored response is replayed with `Idempotent-Replayed: true`
Same key, different body	`422`: the key was already used for another request
Same key while the first request is still running	`409`: wait, then retry
First request failed with `5xx`	Not stored, so a retry runs again

Keys are remembered for 24 hours. For launches, calls, and outbound messages, query the related resource or job after a timeout. Never retry a live side effect blindly from generic HTTP middleware. Retry 429 and transient 5xx responses with exponential backoff and jitter. Respect Retry-After; do not retry validation, authentication, ownership, or feature errors without changing the request.

Getting Started

Guides

Idempotency and retries

Read operations

Resource creation

​Read operations

​Resource creation

Read operations

Resource creation