Idempotency
A write can fail after the server has already done the work: the connection drops, the response never arrives. Retried without protection, it would create a second shipment or a second invoice. The Idempotency-Key header prevents that.
Where it is required
Section titled "Where it is required"| Endpoint | Without the header |
|---|---|
POST /shipments (create a shipment) |
400 |
POST /shipments/{id}/cancel (cancel a shipment) |
400 |
POST /invoices (issue an invoice) |
400 |
On every other write the header is accepted and works the same way.
How it works
Section titled "How it works"- The key is a unique string your client picks for one operation, for example a UUID v4 generated once and kept until the first response.
- The key is kept for 24 hours, separately for each installation of an app, together with a fingerprint of the request.
- Same key, same request: you get the first request's response (with
Idempotent-Replayed: true), and the operation does not run again. Kept: a success (2xx) and a definitive refusal (4xx). - Not kept, so the same key runs the request again: a validation failure (
422validation_failed, for example anorder_idnot synced yet), a429, a refusal whose code may pass later (errors) and any5xx. - Same key, another body:
422. A key belongs to one operation only. - Same key while the first request is still running:
409. Retry after a pause.
Example
Section titled "Example"# shipment.json: the request body, described in the referencecurl -X POST "https://api.connectato.com/v1/shipments" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 5f0c8a52-3b1e-4f7a-9d2c-6e8b1a4f7c30" \ -d @shipment.json<?php
use GuzzleHttp\Client;use Ramsey\Uuid\Uuid;
// Generated once for the operation and kept until the first response.$key = Uuid::uuid4()->toString();
$response = (new Client(['base_uri' => 'https://api.connectato.com/v1/']))->post('shipments', [ 'headers' => [ 'Authorization' => 'Bearer '.getenv('ACCESS_TOKEN'), 'Idempotency-Key' => $key, ], 'json' => $body, // the request body, described in the reference]);import crypto from 'node:crypto';
// Generated once for the operation and kept until the first response.const key = crypto.randomUUID();
const response = await fetch('https://api.connectato.com/v1/shipments', { method: 'POST', headers: { Authorization: `Bearer ${process.env.ACCESS_TOKEN}`, 'Content-Type': 'application/json', 'Idempotency-Key': key, }, body: JSON.stringify(body), // the request body, described in the reference});import osimport uuid
import requests
# Generated once for the operation and kept until the first response.key = str(uuid.uuid4())
response = requests.post( "https://api.connectato.com/v1/shipments", headers={ "Authorization": f"Bearer {os.environ['ACCESS_TOKEN']}", "Idempotency-Key": key, }, json=body, # the request body, described in the reference)Retrying
Section titled "Retrying"On a network error, a timeout, a 5xx or a code that may pass later, send the same request with the same key. If the first request was already processed, you get its response and the operation does not run a second time. Generate a new key only for a new operation.