AveeCare

Idempotency

Make POST requests safe to retry with Idempotency-Key.

If a request to create something times out, you cannot tell whether it worked. Retrying could create a duplicate. An idempotency key makes the retry safe.

Why it matters

Networks drop connections and servers restart. With an Idempotency-Key, AveeCare remembers the result of the first request that used the key and returns that same result if you send the request again, instead of doing the work twice.

How to use it

  1. Generate a unique string for each new operation. A random UUID works well. Keys can be up to 255 characters.
  2. Send it in the Idempotency-Key header on POST requests.
  3. If you have to retry, send the same key with the same body.
cURL
curl -X POST "https://api.aveecare.com/v1/patients" \
  -H "Authorization: Bearer $AVEECARE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "firstName": "Eleanor",
  "middleName": "Ann",
  "lastName": "Vance",
  "goesByName": "Peggy",
  "dateOfBirth": "1941-03-14",
  "gender": "Female",
  "primaryLanguage": "Spanish",
  "email": "eleanor.vance@example.com",
  "active": true,
  "status": "Active",
  "lifecycleStage": "Client",
  "serviceType": "StandardCare",
  "address": "1458 Mesquite Lane",
  "city": "Phoenix",
  "state": "AZ",
  "zipCode": "85016",
  "officeId": "6b0e4d1a-2c7f-4a93-8e15-f3d9a7c2b604",
  "referralSourceId": "9c3a1e7d-4b2f-4d86-a0c5-1e8f6b3d2a97",
  "primaryDiagnosisDescription": "Type 2 diabetes with neuropathy",
  "fallRisk": true,
  "preferredCaregiverGender": "Female",
  "schedulingNotes": "Prefers morning visits before 11am.",
  "responsiblePartyName": "Susan Vance-Mitchell",
  "medicaidId": "A12345678",
  "medicareId": "1EG4-TE5-MK73",
  "insuranceProvider": "Mercy Care",
  "insuranceId": "MC00981234",
  "insuranceGroupNumber": "GRP-4410",
  "billingContactName": "Susan Vance-Mitchell",
  "billingContactEmail": "susan.mitchell@example.com",
  "billingContactPhone": "+16025550142",
  "statementDelivery": "Email",
  "paymentMethodPreference": "Card"
}'

AveeCare keeps each key for 24 hours. A replayed response carries the header Idempotent-Replayed: true, so you can tell it apart from the first. The official SDKs generate a key for every POST and reuse it on their own retries.

GET and DELETE requests do not need a key.

Conflicts

Reusing a key with a different request is a mistake the API refuses to guess about. It returns 409 with the code idempotency_conflict. Use a fresh key for every new operation. See Errors.

If the first request with a key is still running when the retry arrives, the retry also gets 409 idempotency_conflict. Wait a moment and send it again.

PreviousRate limitsNextVersioning