Idempotency

The problem

You send a visit and the connection drops before you get the response. Was it created or not? If you just send it again, you might end up with two visits and two units going to the same address. If you don't, the patient might never get a visit.

The Idempotency-Key header solves this: with it, repeating the same request is safe.

How it works

Generate a unique identifier for each visit you create in your system and send it in the Idempotency-Key header of POST /visits. If you have to repeat the request, repeat it with the same key and the same body.

curl -X POST "$SERAD_API_URL/visits" \
  -H "X-Api-Key: $SERAD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-exp-2026-004512-1" \
  -d @aviso.json

• The key is yours: up to 200 characters, any text. Anything longer returns 400 with the type /errors/provider-api/idempotency-key-invalid.
• Keys are scoped to the API key: the same Idempotency-Key sent with two different API keys counts as two different operations.
• They're remembered for 24 hours. After that, the same key would create a new visit.
• "The same body" is compared by its JSON content, not byte for byte: field order and whitespace don't matter.

Choosing a key

The key has to identify the intent to create this visit, not the HTTP request:

• ✅ Something you already have that is unique to that visit: crm-<case number>-<visit number within the case>, or a UUID that you generate and store with the visit before calling the API.
• ❌ A new UUID on every attempt: then each retry is a new request and idempotency is useless.
• ❌ Just the case number, if a single case can have several visits (for example, a visit today and wound care next week).

Safe retries

With the key, the retry strategy for creating a visit looks like this:

1. Generate and store the Idempotency-Key with the pending visit in your database.
2. Send POST /visits.
3. If the response is 201 or 200: store the visit id. Done.
4. If it's a network error, a timeout, a 429 or a 5xx: retry with the same key and the same body, with exponential backoff (see rate limits).
5. If it's a 409 idempotency-in-progress: wait a few seconds and retry the same way.
6. If it's a 400, 401, 403 or 409 idempotency-key-reused: don't retry; it's an error that needs fixing.