Codes d'erreur

`error.code`	HTTP	Cause typique	Que faire
`unauthorized`	401	Clé API manquante/invalide, ou clé provenant d’un autre environnement	Envoyez la clé dans l’en-tête `X-B2B-API-Key` et assurez-vous qu’elle correspond à l’environnement (sandbox, staging ou production).
`missing_api_key`	401	Cette clé API n’a pas été fournie dans l’en-tête	Envoyez la clé dans l’en-tête `X-B2B-API-Key` et assurez-vous qu’elle correspond à l’environnement (sandbox, staging ou production).
`invalid_api_key`	401	La clé API fournie n’est pas valide	Envoyez une clé valide dans l’en-tête `X-B2B-API-Key` et assurez-vous qu’elle correspond à l’environnement (sandbox, staging ou production).
`expired_api_key`	401	La clé API fournie a expiré	Envoyez une clé valide et active dans l’en-tête `X-B2B-API-Key`
`no_account_group`	403	Clé valide mais aucun groupe/aucune permission ne lui est lié	Demandez l’activation/l’attribution des permissions pour cette clé (les comptes staging nécessitent une demande au support ; les permissions sandbox sont automatiques).
`resource_missing`	404	L’identifiant de la ressource n’existe pas ou n’est pas accessible dans votre tenant	Revérifiez l’endpoint et l’ID que vous envoyez.
`invalid_request_params`	400	JSON mal formé, mauvais types ou structure inattendue	Validez le payload avant envoi.
`invalid_api_version` ¹	400	La version d’API `{api_version}` n’est pas prise en charge	Validez la version et utilisez une version supportée.
`missing_api_version` ¹	400	La version d’API n’est spécifiée ni dans l’en-tête ni dans IntegrationGroup	Définissez `X-B2B-API-Version` ou configurez une version par défaut au niveau du groupe.
`api_version_subdomain_mismatch` ¹	400	Le sous-domaine ne correspond pas à la version d’API spécifiée dans l’en-tête `X-B2B-API-Version` ou associée à la clé API	Changez le sous-domaine pour un sous-domaine correct. Utilisez app.b2brouter ou app-staging.b2brouter pour la version legacy (v2025-01-01). Utilisez api.b2brouter ou api-staging.b2brouter pour les versions ultérieures à v2025-10-13.
`parameter_blank`, `parameter_empty`	422	Champs obligatoires manquants/vides	Renseignez les champs obligatoires puis renvoyez la requête.
`parameter_inclusion`	422	Valeur absente du catalogue autorisé (par ex. un `scheme` invalide)	Vérifiez les valeurs autorisées (voir le Schemes Guide / listes) et corrigez.
`parameter_taken`	422	Une valeur unique existe déjà (par ex. numéro de facture)	Utilisez une nouvelle valeur ou faites un GET avant pour éviter les doublons.
`parameter_cannot_change`	422	Tentative de modification d’un champ immuable	Supprimez le champ de la mise à jour ou créez une nouvelle ressource.
`conflict`	409	L’état actuel de la ressource refuse l’opération	Résolvez le conflit d’état, puis réessayez.
(no code)	429	Vous avez dépassé la limite de débit	Implémentez un backoff exponentiel, mettez en cache et privilégiez les webhooks au polling.

Exemples rapides

1) 401 Unauthorized (clé API erronée/manquante ou mauvais environnement)

Exemple de requête :

curl --request GET \
  --url 'https://api-staging.b2brouter.net/accounts?offset=0&limit=25' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

Exemple de réponse :

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API Key provided, or the API key might not have the necessary permissions for this action.",
    "type": "invalid_request_error"
  }
}

Assurez-vous d’utiliser la bonne clé pour votre environnement (sandbox test_…, staging ou production) et de l’envoyer dans X-B2B-API-Key.

2) 404 Not Found (la ressource n’existe pas ou n’est pas accessible)

Exemple de requête :

curl --request GET \
  --url https://api-staging.b2brouter.net/directory/es/ES1234567890 \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

Exemple de réponse :

{
  "error": "Not found"
}

3) 422 Unprocessable Entity (erreurs de validation)

Exemple de requête :

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/transports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json' \
  --header 'content-type: application/json'
'

Exemple de réponse :

{
  "error": {
    "code": "parameter_taken",
    "message": "Transport type code has already been taken and Peppol Endpoint ID has already been taken",
    "param": "transport_type_code",
    "request_log_url": "https://api-staging.b2brouter.net/api_requests/123456",
    "type": "invalid_request_error"
  }
}

Les échecs de validation renvoient HTTP 422 (Unprocessable Entity) avec des détails d’erreur au niveau des champs, afin que vous puissiez corriger l’entrée et renvoyer la requête si nécessaire.

Traçage des requêtes

Chaque réponse API journalisée inclut l’en-tête X-B2B-API-Request-Id avec l’identifiant unique du log de requête stocké. Vous pouvez utiliser cette valeur pour :

corréler une réponse avec son entrée de log côté serveur ;
la référencer dans les tickets de support pour une investigation plus rapide ;
l’inclure dans les logs de votre propre application pour un traçage de bout en bout.

Les réponses d’erreur incluent également un champ request_log_url dans le corps JSON, qui pointe directement vers le log de requête.

Bonnes pratiques de gestion des erreurs

Authentification : conservez des clés séparées par environnement et envoyez toujours X-B2B-API-Key.
Rate limiting : utilisez un backoff exponentiel, mettez les réponses en cache et préférez les webhooks au polling lorsque c’est possible.
Vocabulaires contrôlés : lorsqu’une valeur doit provenir d’un catalogue (par ex. scheme), vérifiez d’abord l’API/le guide Schemes.