Idempotency

Networks fail. When a request times out you cannot know whether Flashpi received it, and sending it again blindly could issue the same invoice twice, with two sequentials and two access keys. Every POST of the invoicing API therefore accepts an Idempotency-Key header: retry with the same key and Flashpi answers with the result of the first request instead of doing the work again.

curl https://api.flashpi.com.ec/v1/invoices \
  -H "Authorization: Bearer $FLASHPI_API_KEY" \
  -H "Idempotency-Key: 6f1c2a9e-3b7d-4e8a-9c41-2d5f8b0e7a13" \
  -H "Content-Type: application/json" \
  -d @invoice.json

Choosing a key

• 1 to 255 visible ASCII characters (no spaces). A malformed key gets 400 invalid_idempotency_key.
• Use one key per operation you want to happen once: a UUID generated when you create the order, or your own ID of the operation (order-PO-4812, return-RMA-2291). Store it with the operation, so a retry after a crash reuses it.
• Never reuse a key for a different operation.

How it works

Situation	Answer
First request with the key	Processed normally.
Same key, same request, after the first one succeeded	The first answer again (same status and body), with the header Idempotent-Replayed: true. Nothing is issued again.
Same key, same request, while the first one is still running	409 idempotency_key_in_progress. Wait a moment and retry.
Same key, different request	422 idempotency_key_reused.
Same key after the first request failed	Processed as new: a failed request (any error answer) does not keep its key, so you can fix the request and send it with the same key.

• Two requests are the same when the method, the path with its query string and the JSON body match. The order of the keys in the JSON does not matter; any other difference does.
• Keys belong to your account and to the key’s environment: a test key and a live key never share them.
• Only successful (2xx) answers are remembered. A replayed answer has no Location header; the body’s id gives the same path.
• A replay returns the first answer as it was then. To know a document’s current status, read it with GET /v1/documents/{id}.

Retention: 24 hours

Flashpi remembers a key for 24 hours after its first use. After that, the same key is processed as a new request, with one exception that protects your documents:

• A key that created a document stays tied to that document for good. A later request with it, even after 24 hours, gets 422 idempotency_key_reused with the documentId of the document it created, never a second document.

{
  "type": "https://flashpi.com.ec/docs/en/errors/idempotency_key_reused",
  "title": "Idempotency key reused",
  "status": 422,
  "detail": "A document was already created with this Idempotency-Key. Use a new key for a new document.",
  "instance": "/v1/invoices",
  "code": "idempotency_key_reused",
  "errors": [],
  "requestId": "01a15fe0-7a41-7b3c-a9d2-5e8c1f4b6a09",
  "documentId": "01a1412b-ae38-7c39-8c71-16d2b5dfc472"
}

Note

The 24-hour retention and whether the header becomes mandatory for document creation are still to be confirmed before launch. Today the header is optional on every POST, and sending it on every request is strongly recommended.

Retrying safely

1. Generate the key once per operation and keep it.
2. Retry on network errors, timeouts and 5xx answers with the same key and the same body, waiting longer between attempts (for example 1, 2, 4 and 8 seconds).
3. On 409 idempotency_key_in_progress, wait and retry.
4. Do not retry 4xx answers unchanged: fix the request first. A fixed request may reuse the key, because the failed one did not keep it.