Idempotency: safe retries

If a connection breaks after you sent POST /clients, you cannot know whether the client was created. Send an Idempotency-Key and simply retry: Quilo creates the record once and answers the retry with the first result.

curl -X POST "$QUILO_URL/api/v1/sales" \
  -H "Authorization: Bearer $QUILO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: shop-order-10442" \
  -d '{"brand_id":"0b7e9a52-…","receipt_no":"W-10442","total":2480,"channel":"website"}'

Rules#

• Only for POST. PATCH and DELETE are naturally safe to repeat.
• 8 to 100 characters: letters, digits and _ . : -.
• Use a value that is unique for the thing you create, such as your own order number (shop-order-10442) or a UUID you generate and store before sending.
• Keys are remembered for 24 hours, per API key.
• A retry with the same key and the same body returns the stored answer with the header Idempotent-Replayed: true.
• The same key with a different body is refused with 409 conflict, so a reused key cannot hide a mistake.
• Only successful answers (2xx) are stored. After an error you can fix the body and retry with the same key.
• Send retries one after another, not in parallel: two identical requests at the very same moment may both be processed.

Natural uniqueness#

Sales also have a unique receipt_no per brand. Sending the same receipt number twice answers 409 conflict even without an Idempotency-Key. Use GET /sales?receipt_no=W-10442 to find the existing sale.