Guide
Limites, erreurs et idempotence
Ce que l’API répond quand ça ne va pas, comment réessayer, et comment ne jamais créer de doublon.
Les erreurs
Une erreur arrive au format application/problem+json :
{
"title": "unknown_product",
"status": 422,
"detail": "Line 2: product ART-0042 is not in the merchant's catalog."
}
titleest un code stable, écrit pour une machine : c’est lui que votre code teste.detailest une phrase pour un humain : elle peut changer, ne la comparez jamais.
| Statut | Signification | Que faire |
|---|---|---|
400 | Requête mal formée (JSON invalide, paramètre manquant) | Corriger la requête ; ne pas réessayer telle quelle |
401 | Clé absente, inconnue ou révoquée | Arrêter les appels pour ce commerçant et le prévenir |
403 | La clé n’a pas le droit demandé, ou l’abonnement du commerçant est en lecture seule | Demander le droit au commerçant ; lire title (tenant_read_only, tenant_archived) |
404 | Ressource introuvable, ou hors du périmètre de la clé | Vérifier le siteId et l’identifiant |
409 | Conflit : par exemple un e-mail ou un téléphone déjà porté par un autre client | Retrouver la fiche existante au lieu d’en créer une |
422 | Requête valide mais refusée par les règles du commerçant | Lire title, corriger la donnée |
429 | Limite de débit atteinte | Attendre Retry-After secondes, puis réessayer |
5xx | Incident de notre côté | Réessayer plus tard, en espaçant |
L’identifiant de requête
Chaque réponse porte un en-tête X-Request-Id. Gardez-le dans vos journaux : c’est ce que le support vous demandera pour retrouver un appel.
La limite de débit
Chaque clé dispose de 600 appels par minute, avec des rafales jusqu’à 120 appels. Au-delà, l’API répond 429 avec un en-tête Retry-After en secondes :
HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/problem+json
{ "title": "rate_limited", "status": 429, "detail": "Too many requests. Retry after 2 second(s)." }
La limite est comptée par clé (et, pour une application OAuth, par commerçant) : vos clients ne se gênent pas entre eux.
Réessayer proprement
Réessayez seulement ce qui peut réussir plus tard : 429, 5xx, coupure réseau, délai dépassé. Jamais un 4xx autre que 429.
- Après un
429, attendez exactementRetry-After. - Après un
5xxou une coupure, attendez de plus en plus : 1 s, 2 s, 4 s, 8 s… plafonné à une minute, avec un peu de hasard pour ne pas repartir tous ensemble. - Arrêtez après quelques tentatives et signalez l’incident.
async function callGillia(url, options, attempt = 0) {
const res = await fetch(url, options);
if (res.status === 429 || res.status >= 500) {
if (attempt >= 5) throw new Error('Gillia indisponible, requête ' + res.headers.get('X-Request-Id'));
const retryAfter = Number(res.headers.get('Retry-After'));
const wait = retryAfter > 0 ? retryAfter * 1000 : Math.min(60000, 1000 * 2 ** attempt) + Math.random() * 250;
await new Promise(r => setTimeout(r, wait));
return callGillia(url, options, attempt + 1);
}
return res;
}
L’idempotence : jamais de doublon
Une coupure réseau au mauvais moment laisse un doute : la commande est-elle passée ? Pour que vous puissiez réessayer sans risque, les créations qui viennent de votre système portent votre propre référence :
POST /pos/ordersetPOST /pos/partner-orders:externalReference. Le même appel renvoie la même commande (alreadyExisted: true) au lieu d’en créer une seconde.- Gardez la référence de votre côté avant d’appeler, et réutilisez-la à chaque nouvelle tentative.
Les données fiscales
Les tickets de caisse et les clôtures (Z) sont scellés par la caisse certifiée : l’API les lit, ne les modifie jamais. Une commande que vous envoyez devient une vente quand le commerçant l’encaisse à la caisse.