Aller au contenu principal

Gestion des erreurs et bonnes pratiques

Gestion des erreurs​

Les erreurs métier sont renvoyées sous forme RFC7807 / Problem Details.

En plus des champs standards type, title, status, detail et instance, la charge peut inclure :

  • correlationId ;
  • un code métier ;
  • une structure errors détaillant les violations de validation.

Codes HTTP courants​

CodeSignification
400 Bad RequestPayload invalide, paramètre manquant ou combinaison de données incohérente.
401 UnauthorizedToken absent, invalide ou expiré.
403 ForbiddenTenant non possédé par le partenaire, header x-tenant incohérent ou règle d'autorisation métier non satisfaite.
404 Not FoundTenant, legal unit ou office introuvable dans le périmètre courant.
409 ConflictRessource déjà existante, action rejouée dans un état incompatible ou tentative d'approbation / création redondante.
429 Too Many RequestsLa limite de requêtes a été atteinte. Le client doit attendre avant de renouveler l'appel et appliquer une stratégie de retry avec backoff exponentiel.

Les limites de requêtes applicables et les règles générales de reprise associées sont décrites dans les Integration Guidelines BCSolutions, section « Limitation du nombre de requêtes (rate limiting) ».

Journalisation conseillée

Conservez au minimum :

  • timestamp ;
  • tenantSlug ;
  • endpoint appelé ;
  • code HTTP ;
  • correlationId de la réponse ;
  • x-correlation-id émis ;
  • identifiants métier retournés : jobRunId, legalUnitId, officeId, apiAccessId, etc.

Bonnes pratiques d'intégration​

  • Utiliser des UUID pour x-correlation-id et les propager dans toute la chaîne applicative du partenaire.
  • Implémenter des retries prudents avec backoff exponentiel sur les erreurs transitoires, notamment 429, 500, 503 et les timeouts réseau, et non sur les erreurs métier explicites.
  • Maîtriser la cadence des traitements batch et éviter l'envoi simultané d'un grand nombre de requêtes pouvant entraîner le déclenchement du mécanisme de limitation.
  • Rendre idempotentes les opérations de création côté partenaire, en particulier la création de tenant, de legal unit et d'office.
  • Éviter de déclencher automatiquement /public-api-access/{apiAccessId}/rotate sans contrôle opérateur.
  • Ne jamais journaliser un clientSecret ou un access token en clair.
  • Valider les identifiants SIREN / SIRET dans le directory avant de créer l'office lorsque c'est possible.
  • Traiter le provisioning comme asynchrone et distinguer clairement un accusé de mise en file d'une réussite complète de bout en bout.
  • Utiliser une adresse principalUserEmail distincte pour chaque tenant.
  • Documenter dans votre propre système les liens entre tenantSlug, legalUnitId, officeId, apiAccessId et clientId.

Références​

  • OpenAPI / Swagger des myBCS Partners API — référence contractuelle des endpoints, payloads et codes de retour.
  • Integration Guidelines BCSolutions — règles transverses de sécurité, OAuth, journalisation et gestion d'erreurs.
  • Guides des APIs métier du tenant — pour les appels effectués au nom du tenant une fois les credentials bootstrap obtenus et utilisés.
Statut du guide

Ce guide est une synthèse opérationnelle destinée aux partenaires.

En cas d'écart entre ce guide et la spécification OpenAPI publiée pour un environnement donné, la spécification OpenAPI fait foi pour le contrat technique, tandis que les règles d'exploitation et de sécurité demeurent applicables telles qu'énoncées dans le guide.