Errores y reintentos

El formato de los errores de la API, todos sus códigos y la cabecera Idempotency-Key para reintentar un POST sin riesgo de duplicados.

#El formato de un error

Un error responde con un estado HTTP 4xx o 5xx y siempre el mismo cuerpo:

{
  "erreur": {
    "code": "client_introuvable",
    "message": "Ningún cliente coincide en este comercio."
  }
}

• code es estable: es lo que tu programa debe comprobar.
• message es una frase legible, para tus registros. Su texto puede cambiar.

#Los códigos

#Reintentar sin duplicados: Idempotency-Key

La red se corta en el peor momento y no sabes si la visita se ha registrado. Para reintentar sin riesgo, envía en cada POST (/clients, /passages, /recompenses) una cabecera Idempotency-Key: un valor único por operación, de 1 a 200 caracteres, por ejemplo el número del ticket.

curl https://app.stampywallet.com/v1/passages \
  -H "Authorization: Bearer sw_live_votre_cle" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-2026-10-25-0042" \
  -d '{"client": {"telephone": "+33612345678"}, "montant": 12.50}'

• La respuesta se guarda 24 horas. La misma clave repetida devuelve el mismo estado y el mismo cuerpo, con la cabecera Idempotent-Replayed: true.
• Un error 4xx también se guarda: repetirlo devuelve el mismo error. Un error 500 libera la clave, para que puedas reintentar.
• Mientras la primera petición sigue en curso: 409 requete_en_cours.