Erreurs

Toutes les erreurs de l’API native et de l’API hub suivent la RFC 9457 (Content-Type: application/problem+json). Seule exception : l’adaptateur WsOne, qui répond toujours HTTP 200 avec un responseCode (voir Flux WsOne).

Format

{
  "type": "https://remizo.dev/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "lines[2].qty must be > 0",
  "instance": "/v1/transactions/evaluate",
  "code": "validation-failed",
  "traceId": "c1f7a0e2-…",
  "errors": [ { "path": "/lines/2/qty", "message": "must be > 0", "rule": "exclusiveMinimum" } ]
}

• code reprend le dernier segment de type : c’est lui qu’il faut tester dans votre code ;
• traceId est la valeur de X-Request-Id : communiquez-le au support ;
• errors[] détaille les problèmes champ par champ (pointeur JSON).

Statuts HTTP

Statut	Sens	Que faire
400	JSON mal formé	corriger la requête
401	non authentifié	vérifier la clé ou le jeton
403	portée, magasin ou workspace non autorisé	vérifier les droits de la clé ou de l’utilisateur
404	ressource introuvable (ou fonctionnalité désactivée : feature-disabled)	vérifier l’identifiant
409	conflit d’état (ticket déjà validé, solde insuffisant…)	lire code, ne pas réessayer à l’identique
412	If-Match ne correspond plus (brouillon d’offre modifié entre-temps)	recharger puis réappliquer
422	validation sémantique (magasin inconnu, devise, lineNo en double)	corriger les données
429	limite de débit	attendre Retry-After secondes
501	non implémenté (assistant IA)	—
503	moteur en drainage ou base indisponible	réessayer après Retry-After, sur une autre instance

Codes du moteur

Code	Statut	Signification
validation-failed	400/422	ticket non conforme au schéma
unauthorized	401	clé absente ou invalide
forbidden-scope	403	portée manquante
forbidden-store	403	magasin non autorisé pour la clé
not-found	404	transaction, réservation, client introuvable
idempotency-key-reused	422	même Idempotency-Key, corps différent
ticket-key-committed	409	la clé de ticket est déjà validée
transaction-not-committable	409	ticket annulé, expiré, ou coupon consommé ailleurs
transaction-not-cancellable	409	fenêtre d’annulation dépassée ou remboursement existant
transaction-not-refundable	409	ticket non validé ou quantités épuisées
insufficient-balance	409	solde disponible insuffisant
reservation-not-confirmable / reservation-not-cancellable	409	réservation déjà résolue ou expirée
coupon-not-redeemable	409	coupon utilisé, expiré, réservé ou n’appartenant pas au client
customer-unknown / customer-blocked	404/409	client inconnu ou bloqué
unknown-store	422	magasin non déclaré dans le workspace
currency-mismatch	422	devise différente de celle du workspace
rate-limited	429	limite de débit de la clé
engine-unavailable	503	moteur en drainage ou base indisponible
internal	500	erreur inattendue (traceId à transmettre)

Les codes du hub (workspace-not-in-token, last-owner, feature-disabled, not-implemented…) sont listés dans la référence de l’API hub.

Un ticket n’est jamais refusé pour une offre

Les offres non applicables ne sont pas des erreurs : elles figurent dans rejected[] avec leur raison, et la réponse reste 200. De même, les incohérences de montants produisent des avertissements (warnings[]) et jamais un refus.

Côté caisse

Prévoyez un repli : en cas de délai dépassé ou d’erreur 5xx, encaissez sans avantage et rejouez le ticket plus tard avec la même clé de ticket (l’idempotence protège des doubles crédits).