Idempotency
Use the Idempotency-Key header to send an inbound load safely more than once.
An idempotency key stops the same load from being processed twice when you retry it, for example after a timeout or a dropped connection. Use this page to send a key and to read what GAINS Connect answers when it sees a key again.
Send a key
Add an Idempotency-Key header to a load 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
GAINS Connect records the key when the request arrives. For the next 24 hours, any request in the same scope (see Rules) 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. To find the task the first request created, list your tasks with GET /tasks, filtered by TaskType and date.
After 24 hours the key is forgotten and a request that uses it is processed as new.
Rules
| Rule | Detail |
|---|---|
| Length | Up to 255 characters. A longer key is refused with 400. |
| 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 is three separate keys. A few related endpoints share one scope, for example POST /calendar/daily, POST /calendar/weekly and POST /calendar/monthly. |
| Window | 24 hours from the first request that used the key. |
| Empty key | An empty header is ignored. |
Which endpoints support it
Every data load and delete endpoint, for example POST /skus and POST /skus/delete. GET requests, task, webhook and custom-route endpoints ignore the header.
Retry safely
The key is recorded before the request is validated, so it is used up even when the request fails, unless the failure is 429.
| First response | Next step |
|---|---|
202, 207 | Done. Do not resend; the data is queued. |
429 | Wait for Retry-After, then resend the same batch with the same key. The key was released. |
No response, timeout, 500, 504, and any 503 not listed below | Resend with the same key. If that answers 400 with The idempotency key indicates a duplicate payload., the first request arrived: call GET /tasks with its TaskType and a DateStart just before the first attempt. A task with the right record count means the batch was accepted; none means it failed after the key was recorded, so send it under a new key. |
400, 403, 422 | Fix the request, then send it with a new key. |
401, 426, and a 503 saying the feature is not configured for your environment | Fix the cause, then resend with the same key. These are answered before the key is recorded. |
Related
Updated 5 days ago