REST, JSON, erreurs et asynchronisme

Conventions REST / JSON

Les exemples de documentation et d'intégration doivent :

• distinguer endpoint, headers, request body et response body ;
• utiliser des payloads JSON indentés avec deux espaces ;
• utiliser des dates ISO 8601 avec fuseau ou suffixe Z lorsque requis ;
• ne pas considérer les valeurs d'exemple comme contractuelles lorsqu'une contrainte OpenAPI différente existe.

Pagination et recherche

Les mécanismes varient selon la famille d'API.

API	Mécanisme courant
Directory Service	limit + ignore, réponses search + totalNumberOfResults + results
Flow Service	recherche via where, suivi différentiel avec updatedAfter, selon le contrat de l'environnement
Partner APIs	selon endpoint : listes paginées ou réponses de dispatch asynchrones

Gestion des erreurs

La gestion doit s'appuyer sur le code HTTP et la structure d'erreur retournée. Les messages lisibles ne doivent pas être utilisés comme clé de traitement automatique.

Certaines APIs peuvent retourner un modèle simple :

{
  "errorCode": "SEC_TOKEN_EXPIRED",
  "errorMessage": "The access token has expired"
}

D'autres peuvent exposer un format Problem Details :

{
  "type": "https://docs.mybcs.fr/problems/validation-error",
  "title": "Validation error",
  "status": 400,
  "detail": "One or more fields are invalid.",
  "correlationId": "7e8ffbaa-6f65-4ee8-a7d9-28f019aa9e5e",
  "code": "VALIDATION_ERROR"
}

Codes HTTP fréquents

Les codes ci-dessous constituent des conventions transverses pouvant être retournées par les API de la plateforme. Leur présence dans ce tableau ne signifie pas qu’ils font partie du catalogue normatif d’erreurs de chaque API. En particulier, 429 Too Many Requests correspond au mécanisme transverse de rate limiting de la plateforme et non à un code d’erreur défini par le standard AFNOR du Flow Service ou du Directory Service.

HTTP	Interprétation	Action recommandée
400	Requête invalide	Corriger ; ne pas retry automatiquement
401	Token absent, invalide ou expiré	Renouveler le token / vérifier les credentials
403	Accès interdit ou contexte incohérent	Vérifier scopes, ownership et headers
404	Ressource non trouvée	Vérifier identifiant et contexte
409	Conflit d'état / ressource existante	Vérifier idempotence et état métier
413	Payload ou fichier trop volumineux	Corriger taille ou type de dépôt
422	Requête non traitable fonctionnellement	Corriger le document ou les règles métier
429	Limite d’utilisation dépassée / rate limiting	Suspendre les appels, respecter Retry-After s’il est présent, puis reprendre avec backoff + jitter
500 / 503	Erreur plateforme / indisponibilité transitoire	Retry contrôlé

Erreur HTTP vs rejet asynchrone

Une erreur HTTP immédiate signifie que l'appel n'a pas été accepté ou ne peut pas être traité dans son état courant.

Un traitement asynchrone peut au contraire être accepté puis échouer ultérieurement. Le résultat final doit alors être lu dans les objets métier ou statuts de suivi de la famille d'API concernée.