Idempotency
Use the Idempotency-Key header to resend a load or delete safely, and choose the key when you resend.
An idempotency key stops the same batch from being loaded twice when you resend it, for example after a timeout or a dropped connection. Use this page to send a key, to read what GAINS Connect answers when it sees a key again, and to choose the key when you resend.
Send a key
Add an Idempotency-Key header to a load or delete request. Generate a new value for each distinct batch; a version 4 UUID is a good choice.
POST /api/v1/customers HTTP/1.1
Host: acme.gainsystems.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJqTl9F...
Content-Type: application/json
Idempotency-Key: 9b2f6c1e-4a7d-4e3b-8f05-1d6a2c9e7b40
[
{
"CustomerCode": "C-10452",
"Name": "Midwest Industrial Supply",
"ShipToCode": "ST-01"
}
]The key is optional. Without it, every request is processed.
What happens when you reuse a key
For 24 hours after a key is recorded, any request in the same scope (see Scope) with the same key is refused with 400, whatever its body:
{
"Reason": "The idempotency key indicates a duplicate payload."
}GAINS Connect does not return the original response; see Which key to resend with for what to do next.
After 24 hours the key is forgotten and a request that uses it is processed as new.
Which key to resend with
| You got | Resend with |
|---|---|
| No response, for example a timeout or a dropped connection | The same key. You cannot tell whether the first request was accepted. |
429 | The same key. A 429 releases the key, and nothing was saved. |
Any other error response, 4xx or 5xx | A new key. Nothing from the request was saved. |
400 The idempotency key indicates a duplicate payload. | Nothing yet. Check first, as below. |
A resend under the same key answers that it is a duplicate in two cases, and the answer looks the same for both:
- The first request was accepted, but its response never reached you. The batch is already in a task: sending it under a new key would load it twice.
- The first request failed after its key was recorded, and that error never reached you either. Nothing was saved, and the key cannot be used again for 24 hours.
To tell them apart, list your tasks with GET /tasks, filtered by TaskType and a DateStart just before the first attempt. A task with the right record count means the batch was accepted: do not resend. None means it was not: send the batch again under a new key.
Whether to resend at all is in Decide whether to retry.
Scope
A key is tracked per kind of data, and a load and its delete are separate kinds: the same key on POST /customers, POST /customers/delete and POST /locations counts as three separate keys. A few endpoints load the same kind of data and share one scope:
POST /demand-transactionsandPOST /demand-transactions-splitsPOST /supply-transactions,POST /supply-transactions-splitsandPOST /supply-transactions/link-orderPOST /calendar/daily,POST /calendar/weeklyandPOST /calendar/monthlyPOST /lia-input/weeklyandPOST /lia-input/monthly
A key used on one endpoint of a group is therefore refused on the others for 24 hours.
Which endpoints support it
Every data load and delete endpoint, for example POST /skus and POST /skus/delete. GET requests, task and webhook endpoints, and POST /custom/{ApiRoute} ignore the header.
Related
- Errors & Retries: whether to retry each status.
- Load Throughput & Retries:
429and backoff. - Loading Data: the submit responses.
- Integration Tasks: finding the task a batch created.
Updated 13 days ago
