Erreurs et retry

Des statuts HTTP réels — jamais de « 200 + flag d'erreur » — et un corps normalisé. Le comportement de retry de la borne dépend directement de vos statuts : les respecter n'est pas cosmétique.

Le corps d'erreur normalisé

json

{ "error": { "code": "UNKNOWN_APPOINTMENT", "message": "Appointment apt-1001 not found", "details": null } }

message est destiné aux logs (jamais affiché au patient) : mettez-y de quoi diagnostiquer. details est libre (champ en faute, limite dépassée…). Le module d'erreurs de la démo tient en un fichier : src/server/contract/errors.ts.

Les codes du contrat

Code	HTTP	Sens
`INVALID_AUTH_KEY`	401	Clé partagée incorrecte pour ce device
`UNKNOWN_DEVICE`	401	Device non provisionné (validé en premier)
`INVALID_CREDENTIALS`	401	staff/sign-in : identifiants invalides
`VALIDATION_ERROR`	400	Corps ou paramètre invalide
`UNKNOWN_PATIENT`	404	Patient introuvable
`UNKNOWN_APPOINTMENT`	404	RDV introuvable (id ou code)
`UNKNOWN_DOCUMENT`	404	Document introuvable / déjà supprimé
`ALREADY_CHECKED_IN`	409	Check-in impossible : état réellement incompatible
`UPLOAD_TOO_LARGE`	413	Upload au-delà de votre limite (≥ 10 Mo à accepter)
`INTERNAL_ERROR`	500	Erreur interne (retentée par la borne)
`NOT_SUPPORTED`	501	DÉPRÉCIÉ — toutes les routes sont obligatoires : répondez la forme minimale (liste vide, 204, 404…)

Politique de retry de la borne

Votre statut HTTP pilote directement le comportement de la borne — un mauvais statut casse le mécanisme de retry.

Erreurs réseau et 5xx : retentées (nombre et plage horaire configurables côté borne) ;
4xx : jamais retentés — la borne les considère définitifs.

Conséquence directe : vos opérations d'écriture doivent tolérer un rejeu après timeout. Le cas critique est le check-in — idempotence détaillée sur sa page de référence. Un mauvais statut (500 à la place d'un 404, 200 avec flag d'erreur…) casse ce mécanisme.