Skip to content
StampyWalletDocs
API and webhooks / Get started / Errors

Errors and retries

The API error format, all error codes, and the Idempotency-Key header to retry a POST with no risk of duplicates.

Error format

An error responds with an HTTP 4xx or 5xx status and always the same body:

Error response
{
  "erreur": {
    "code": "client_introuvable",
    "message": "No customer matches in this business."
  }
}
  • code is stable: it is what your program should test.
  • message is a readable sentence, for your logs. Its text may change.

Codes

StatusCodes
400requete_invalide (unreadable JSON), client_requis, recherche_requise, montant_invalide, quantite_invalide, points_invalide, email_invalide, telephone_invalide, idempotency_key_invalide
401non_authentifie, cle_revoquee, signature_invalide (incoming addresses)
403formule_requise (the API requires the Growth plan), interdit
404introuvable (address), client_introuvable, passage_introuvable
409trop_tot, pas_dernier, deja_annule, recompense_offerte, aucune_recompense, requete_en_cours
422conditions_requises, montant_insuffisant
429trop_de_requetes (see the rate limit)
500interne: try again later, with the same Idempotency-Key

Retry without duplicates: Idempotency-Key

The network drops at the wrong moment, and you don't know whether the visit was recorded. To retry safely, send an Idempotency-Key header on every POST (/clients, /passages, /recompenses): a unique value per operation, from 1 to 200 characters, for example the receipt number.

curl
curl https://app.stampywallet.com/v1/passages \
  -H "Authorization: Bearer sw_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-2026-10-25-0042" \
  -d '{"client": {"telephone": "+33612345678"}, "montant": 12.50}'
  • The response is kept for 24 hours. The same key replayed returns the same status and the same body, with the header Idempotent-Replayed: true.
  • A 4xx error is kept too: replaying it returns the same error. A 500 error releases the key, so you can try again.
  • While the first request is still running: 409 requete_en_cours.

Tip : on POST /v1/passages, the reference field (your receipt number) also protects you: the same reference only adds a stamp once per business, even without Idempotency-Key.

Updated

Was this page helpful?