Skip to content
Gillia Developers v1

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."
}
  • title est un code stable, écrit pour une machine : c’est lui que votre code teste.
  • detail est une phrase pour un humain : elle peut changer, ne la comparez jamais.
StatutSignificationQue faire
400Requête mal formée (JSON invalide, paramètre manquant)Corriger la requête ; ne pas réessayer telle quelle
401Clé absente, inconnue ou révoquéeArrêter les appels pour ce commerçant et le prévenir
403La clé n’a pas le droit demandé, ou l’abonnement du commerçant est en lecture seuleDemander le droit au commerçant ; lire title (tenant_read_only, tenant_archived)
404Ressource introuvable, ou hors du périmètre de la cléVérifier le siteId et l’identifiant
409Conflit : par exemple un e-mail ou un téléphone déjà porté par un autre clientRetrouver la fiche existante au lieu d’en créer une
422Requête valide mais refusée par les règles du commerçantLire title, corriger la donnée
429Limite de débit atteinteAttendre Retry-After secondes, puis réessayer
5xxIncident 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.

  1. Après un 429, attendez exactement Retry-After.
  2. Après un 5xx ou 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.
  3. 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/orders et POST /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.