Aller au contenu
Gatebold

Référence cXML

Codes d'erreur cXML - référence complète.

36 codes Status officiels (200, 401, 406, 450, 475, 500, etc.) sourcés du cXML Reference Guide v1.2.070. Plus 15 pièges fréquents hors codes (encoding, payloadID, SharedSecret, etc.). Causes, debug, fix.

Cette page liste tous les codes Status cXML documentés dans cXML Reference Guide version 1.2.070 .

HTTP vs cXML : les 2 niveaux d'erreur dans une réponse

Une réponse buyer contient deux codes distincts à deux endroits différents : le code HTTP dans les en-têtes, et le code cXML dans le corps XML. Cette page documente principalement les codes cXML, et liste séparément les codes HTTP transport (404, 502, 504, etc.) souvent confondus avec. 

# Ce que vous recevez quand vous faites POST vers un buyer cXML :

HTTP/1.1 200 OK  ← code HTTP (transport)
Content-Type: text/xml
Content-Length: 458

<?xml version="1.0"?>
<cXML payloadID="..." timestamp="...">
  <Response>
    <Status code="401" text="Unauthorized">  ← code cXML (contenu)
      SharedSecret mismatch
    </Status>
  </Response>
</cXML>

Dans cet exemple, le transport HTTP a réussi (le message est bien arrivé au buyer) mais le cXML a échoué (le buyer rejette l'authentification). Le piège classique : un dev voit HTTP 200 dans ses logs et conclut "tout va bien" sans parser le XML - alors que la commande n'a jamais été acceptée.

Référence des codes cXML

36 codes Status officiels + 15 pièges hors codes. Sourcé du cXML Reference Guide v1.2.070 (16/05/2026).

cXML 1.2.070
Sévérité : Info succès, rien à faire Permanente corrigez la requête, ne retry pas Transitoire (retry) temporaire, retry avec délai
Filtrer

Codes Success (2xx)

  • cXML 200 OK

    Info

    Le serveur a pu exécuter la requête ou la délivrer au destinataire final. La réponse peut contenir des warnings ou des erreurs applicatives - le 200 ne reflète que le bon traitement du protocole cXML, pas les erreurs métier ultérieures.

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • Succès normal du flux PunchOutSetup, PunchOutOrderMessage, ConfirmationRequest, etc.

    Exemple XML 

    <Status code="200" text="OK">Succeeded</Status>

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 201 Accepted

    Info

    La requête a été acceptée pour transmission par un hub intermédiaire, ou acceptée par le destinataire final sans avoir encore été examinée. Le client doit s'attendre à recevoir un StatusUpdateRequest ultérieur.

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • OrderRequest envoyé via Ariba Network en mode asynchrone
    • Document accepté pour traitement différé côté supplier

    Checklist debug

    • Vérifier la réception du StatusUpdateRequest ultérieur (peut prendre quelques minutes à plusieurs heures)
    • Logger le payloadID pour pouvoir corréler avec le StatusUpdate

    Codes liés

    280 281

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 204 No Content

    Info

    Toutes les informations de la Request étaient valides et reconnues, mais le serveur n'a pas de données de réponse du type demandé. Dans un PunchOutOrderMessage, ce code indique la fin de session sans modification du panier.

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • L'utilisateur a quitté le catalogue PunchOut sans rien ajouter au panier (cancel)
    • Requête asynchrone légitime sans payload de retour

    Codes liés

    200 280

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 211 OK

    Info

    Code utilisable par les acheteurs (buyers) pour diffuser un message d'information aux fournisseurs (planning des fermetures, événements, complétion d'opérations comme un planning run, etc.). N'indique pas une action requise du supplier.

  • cXML 280 Forwarded

    Info

    La requête a été transmise par un hub intermédiaire. Le client recevra au moins une mise à jour de statut supplémentaire. Cela peut signifier que la requête a été délivrée à un autre intermédiaire (lui-même répondant 201) ou au destinataire final.

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • Routing via Ariba Network qui transmet vers un autre hub
    • Transit par un middleware d'entreprise

    Codes liés

    201 281

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 281 Forwarded (unreliable transport)

    Info

    La requête a été transmise par un hub intermédiaire via un transport non fiable (email par exemple). Les mises à jour de statut peuvent ne pas arriver - leur absence n'est pas forcément un problème.

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • Routage email/fax côté Ariba Network pour un supplier non configuré en cXML temps réel

    Codes liés

    280

    Source: cXML Reference Guide v1.2.070, §3.1.9

Erreurs permanentes générales (4xx)

  • cXML 400 Bad Request

    Permanente

    Requête inacceptable pour le serveur, bien que le XML ait été correctement parsé. C'est une erreur de contenu, pas de syntaxe (pour la syntaxe, voir 406).

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • BuyerCookie absent ou invalide dans un PunchOutOrderMessage
    • Valeur d'attribut hors enum (operation, type, etc.)
    • Référence à un objet inexistant côté serveur

    Checklist debug

    • Logger le contenu textuel de l'élément Status (souvent un message exploitable)
    • Comparer le XML envoyé avec un PunchOutOrderMessage validé connu
    • Vérifier les attributs requis sur tous les éléments

    Fix typique

    Lire le message de Status renvoyé par le serveur, corriger l'élément ou l'attribut fautif, retester.

    Exemple XML 

    <Status code="400" text="Bad Request">Invalid Document. Unable to extract BuyerCookie.</Status>

    Codes liés

    406 412 417

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 401 Unauthorized

    Permanente

    Les credentials fournis dans la requête (élément Sender) ne sont pas reconnus par le serveur. Cause numéro 1 d'échec en intégration cXML.

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • SharedSecret mal renseigné (copier-coller avec espaces invisibles ou retour chariot)
    • Domain incorrect dans Credential (ex: NetworkID au lieu de DUNS)
    • Identity sensible à la casse non respectée (ANID Ariba en majuscules strictes)
    • Sender configuré pour un environnement différent (test vs prod)

    Checklist debug

    • Trim systématique du SharedSecret avant envoi
    • Hex-dump du SharedSecret stocké pour traquer les caractères invisibles
    • Comparer letter-by-letter le `domain` et `identity` reçus avec la config supplier dans Ariba Network
    • Vérifier que From, Sender et Credential pointent vers la bonne entité

    Fix typique

    Re-synchroniser le SharedSecret avec le buyer via leur portail. Si l'erreur persiste, vérifier l'alignement exact des champs From/Sender/Credential.

    Codes liés

    403 412

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 402 Payment Required

    Permanente

    Cette requête doit inclure un élément Payment complet. En pratique très rare en intégration PunchOut.

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • Buyer en retard de paiement Ariba (cas hub)
    • Flux PCard incomplet

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 403 Forbidden

    Permanente

    L'utilisateur dispose de privilèges insuffisants pour exécuter cette requête. L'identité est correctement reconnue (sinon 401) mais l'action est interdite.

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • Compte buyer désactivé
    • Type de document non autorisé pour cette identité (ex: InvoiceDetailRequest sans droit)
    • Configuration de permissions côté supplier ou buyer

    Checklist debug

    • Vérifier le statut du compte côté buyer (actif/suspendu)
    • Vérifier le type de document accepté pour ce supplier

    Codes liés

    401

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 406 Not Acceptable

    Permanente

    Requête inacceptable pour le serveur, généralement à cause d'un échec de parsing. C'est l'erreur typique remontée quand le XML n'est pas conforme au DTD cXML.

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • XML mal formé (balise non fermée, ordre invalide)
    • Élément requis manquant
    • Attribut hors enum déclaré dans le DTD
    • Encodage différent du déclaré dans <?xml ?>
    • URL du DTD inaccessible et validation activée

    Checklist debug

    • Valider le XML contre le DTD officiel cXML 1.2.070 (notre validateur cXML le fait gratuitement)
    • Vérifier la déclaration <!DOCTYPE> en tête
    • Inspecter le contenu textuel de Status (souvent l'erreur du parser y est)

    Fix typique

    Utiliser notre validateur cXML pour identifier l'élément/attribut fautif, puis corriger.

    Exemple XML 

    <Status code="406" text="Not Acceptable">cXML did not validate. Big Problem!</Status>

    Codes liés

    400 412

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 409 Conflict

    Permanente

    L'état actuel du serveur ou de ses données internes a empêché l'opération de mise à jour. Une requête identique a peu de chances de réussir à l'avenir, sauf si une autre opération a été exécutée entre-temps.

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • payloadID dupliqué (replay d'un message déjà reçu)
    • Tentative de modification d'une commande déjà confirmée/expédiée
    • Tentative de création d'un objet déjà existant

    Checklist debug

    • Vérifier l'unicité du payloadID (format recommandé: `timestamp.process.counter@domain`)
    • Tracer l'état de la commande côté buyer avant le retry

    Fix typique

    Régénérer un payloadID unique à chaque envoi. NE PAS retry mécaniquement sur 409 - le conflit ne se résoudra pas tout seul.

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 412 Precondition Failed

    Permanente

    Une précondition de la requête n'est pas remplie. Par exemple, une session PunchOut appropriée pour un PunchOutSetupRequest 'edit'. Indique souvent que le client a ignoré une portion d'une transmission précédente du serveur.

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • BuyerCookie absent ou modifié entre Setup et OrderMessage
    • Tentative d'opération 'edit' sur une session sans permission d'édition
    • operationAllowed du PunchOutOrderMessageHeader ignoré

    Fix typique

    Conserver le BuyerCookie reçu au Setup et le rejouer à l'identique. Respecter operationAllowed.

    Codes liés

    400 401

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 417 Expectation Failed

    Permanente

    La requête implique une condition de ressource non satisfaite. Exemple : un SupplierDataRequest qui demande des infos sur un supplier inconnu du serveur. Peut indiquer une perte d'information côté client ou serveur.

  • cXML 450 Not Implemented

    Permanente

    Le serveur n'implémente pas cette requête spécifique. Par exemple, PunchOutSetupRequest ou l'opération demandée pourrait ne pas être supportée. Indique généralement que le client a ignoré le profile du serveur.

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • Document type non supporté par le supplier (ex: OrderRequest envoyé à un supplier PunchOut-only)
    • Operation `edit`/`inspect` envoyée à un supplier qui ne la supporte pas
    • Version cXML déclarée non supportée

    Checklist debug

    • Vérifier les capabilities du supplier via son ProfileResponse
    • Consulter la documentation buyer sur les opérations PunchOut supportées

    Fix typique

    Utiliser un type de document supporté ou demander au supplier d'implémenter la nouvelle opération.

    Source: cXML Reference Guide v1.2.070, §3.1.9

Signatures numériques (475-477)

  • cXML 475 Signature Required

    Permanente

    Le destinataire refuse le document parce qu'il ne contient pas de signature numérique. Ne pas confondre avec une erreur générique de PunchOut.

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • Le buyer exige des messages signés (config sécurité renforcée)
    • InvoiceDetailRequest non signé envoyé à un buyer qui requiert la signature

    Fix typique

    Implémenter la signature cXML (signatureVersion='1.0' et signature XML conforme à la section 23 du Reference Guide).

    Codes liés

    476 477

    Source: cXML Reference Guide v1.2.070, §23.2.2

  • cXML 476 Signature Verification Failed

    Permanente

    Le destinataire ne peut pas valider la signature, possiblement parce que le document a été altéré en transit, ou parce que le destinataire ne supporte pas un ou plusieurs algorithmes utilisés.

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • Document modifié par un middleware (proxy qui ré-encode l'XML)
    • Algorithme de signature non supporté (SHA-512 par exemple)
    • Certificat expiré ou révoqué

    Fix typique

    Vérifier que le document n'est pas modifié en transit. Aligner l'algorithme avec ce que le buyer supporte (souvent RSA-SHA256).

    Codes liés

    475 477

    Source: cXML Reference Guide v1.2.070, §23.2.2

  • cXML 477 Signature Unacceptable

    Permanente

    La signature est techniquement valide mais inacceptable pour le destinataire pour une autre raison : politique de signature, politique de certificat, type de certificat utilisé, ou autre problème.

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • Certificat self-signed non accepté
    • Autorité de certification non whitelistée par le buyer
    • Politique de signature non conforme (key length insuffisante par exemple)

    Codes liés

    475 476

    Source: cXML Reference Guide v1.2.070, §23.2.2

Upload de catalogue (461-470, 499, 561-563)

  • cXML 461 Bad Commodity Code

    Permanente

    Le code marchandise (commodity code) assigné au catalogue est invalide.

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • Code UNSPSC mal formé (mauvais nombre de chiffres)
    • Code marchandise inconnu du buyer

    Source: cXML Reference Guide v1.2.070, §3.1.10

  • cXML 462 Notification Error

    Permanente

    Aucune méthode de notification (email ou URL) fournie pour le résultat de l'upload du catalogue.

  • cXML 463 Bad Catalog Format

    Permanente

    Le fichier zip transmis est invalide. Le contenu n'est pas un zip valide ou est corrompu.

  • cXML 464 Bad Catalog

    Permanente

    Aucun catalogue n'est attaché, ou plus d'un catalogue est attaché à la requête. Un seul catalogue doit être présent par upload.

  • cXML 465 Duplicate Catalog Name

    Permanente

    Le nom du catalogue existe déjà côté buyer. Utiliser un nom unique pour la nouvelle version ou mettre à jour l'existant explicitement.

  • cXML 466 No Catalog to Update

    Permanente

    Le catalogue à mettre à jour n'existe pas côté buyer.

  • cXML 467 Publish Not Allowed

    Permanente

    Tentative de publier un catalogue qui n'avait pas été préalablement publié. La première publication suit un workflow différent.

  • cXML 468 Catalog Too Large

    Permanente

    La taille du fichier uploadé dépasse la limite de 4 Mo. Compresser en zip avant upload.

    Détails, causes et fix →

    Fix typique

    Compresser le catalogue en .zip avant upload, ou découper le catalogue en plusieurs publications partielles.

    Source: cXML Reference Guide v1.2.070, §3.1.10

  • cXML 469 Bad Catalog Extension

    Permanente

    Le fichier catalogue doit avoir une extension .cif, .xml ou .zip.

  • cXML 470 Catalog Has Errors

    Permanente

    Le contenu du catalogue contient des erreurs (validation HasErrors). Le buyer renvoie typiquement le détail des erreurs dans le payload de réponse.

  • cXML 499 Document Size Error

    Permanente

    Le document cXML est trop volumineux pour être traité par le destinataire.

    Détails, causes et fix →

    Fix typique

    Découper en plusieurs documents plus petits ou compresser via HTTP gzip si supporté.

    Source: cXML Reference Guide v1.2.070, §3.1.10

  • cXML 561 Too Many Catalogs

    Transitoire (retry)

    Vous ne pouvez pas uploader plus d'un certain nombre de catalogues par heure (rate limit côté buyer).

    Détails, causes et fix →

    Fix typique

    Espacer les uploads. Implémenter une file d'attente côté supplier avec respect du rate limit du buyer.

    Source: cXML Reference Guide v1.2.070, §3.1.10

  • cXML 562 Publish Disabled

    Transitoire (retry)

    La publication de catalogue est temporairement indisponible pour maintenance programmée. Le buyer indique généralement la date/heure de retour en ligne.

  • cXML 563 Catalog Validating

    Transitoire (retry)

    Vous avez tenté de mettre à jour un catalogue avant que la validation de la version précédente ne soit terminée.

    Détails, causes et fix →

    Fix typique

    Attendre la fin de validation (notification de complétion) avant de pousser une nouvelle version.

    Source: cXML Reference Guide v1.2.070, §3.1.10

Erreurs transitoires (5xx)

  • cXML 500 Internal Server Error

    Transitoire (retry)

    Le serveur n'a pas pu compléter la requête. Erreur générique côté récepteur, à retry.

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • Exception non catchée côté récepteur
    • Base de données indisponible
    • Bug applicatif côté serveur

    Checklist debug

    • Vérifier le contenu textuel de Status (souvent contient le détail de l'erreur)
    • Logger le payloadID pour pouvoir investiguer côté supplier ou hub

    Fix typique

    Retry avec backoff exponentiel. Si persistant, ouvrir un ticket au destinataire avec le payloadID.

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 550 Unable to reach cXML server

    Transitoire (retry)

    Impossible d'atteindre le serveur cXML suivant pour compléter une transaction qui requiert des connexions upstream. Un hub intermédiaire peut retourner ce code quand un site supplier est inaccessible.

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • Endpoint supplier down ou timeout
    • Configuration de routing Ariba Network cassée
    • Certificat SSL expiré côté supplier

    Checklist debug

    • Tester l'endpoint supplier directement (curl)
    • openssl s_client pour vérifier le certificat
    • Pinger le DNS, vérifier le firewall

    Codes liés

    551 560

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 551 Unable to forward request

    Transitoire (retry)

    Impossible de transmettre la requête en raison d'une mauvaise configuration côté supplier. Exemple : un hub intermédiaire n'arrive pas à s'authentifier auprès du supplier. Le client ne peut pas corriger cette erreur, mais elle peut être résolue avant que le client ne retry.

    Détails, causes et fix →

    Causes typiques (retour d'expérience)

    • Auth hub→supplier cassée (SharedSecret côté supplier obsolète)
    • URL endpoint supplier modifiée sans mise à jour de la config hub

    Fix typique

    Côté supplier : vérifier la config d'authentification dans Ariba Network. Le client doit attendre la résolution.

    Codes liés

    550

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 560 Temporary server error

    Transitoire (retry)

    Par exemple, un serveur peut être en maintenance. Le client doit retry plus tard.

    Détails, causes et fix →

    Fix typique

    Retry avec backoff exponentiel. Recommandation spec : 10 retries, fréquence 1 heure, fenêtre minimum de 6 heures.

    Source: cXML Reference Guide v1.2.070, §3.1.9

Erreurs HTTP transport (non-cXML)

Ces codes HTTP ne sont PAS des codes cXML, mais sont régulièrement confondus avec. À traiter comme des erreurs transitoires de transport.

  • HTTP 404 Not Found

    Transport

    Erreur HTTP transport, PAS un code cXML. Indique que l'URL endpoint cible est inconnue du serveur. À traiter comme une erreur transitoire (retry après vérification de l'URL).

    Source: cXML Reference Guide v1.2.070, §3.1.9 (transport-level)

  • HTTP 408 Request Timeout

    Transport

    Erreur HTTP transport, PAS un code cXML. Le serveur n'a pas reçu la requête complète à temps. À traiter comme transient error.

    Source: cXML Reference Guide v1.2.070, §3.1.9 (transport-level)

  • HTTP 502 Bad Gateway

    Transport

    Erreur HTTP transport, PAS un code cXML. Un reverse proxy intermédiaire n'a pas pu joindre le serveur cible. Retry, vérifier les timeouts proxy.

    Source: cXML Reference Guide v1.2.070, §3.1.9 (transport-level)

  • HTTP 503 Service Unavailable

    Transport

    Erreur HTTP transport, PAS un code cXML. Service temporairement indisponible (maintenance, rate limit, surcharge). Retry avec backoff.

    Source: cXML Reference Guide v1.2.070, §3.1.9 (transport-level)

  • HTTP 504 Gateway Timeout

    Transport

    Erreur HTTP transport, PAS un code cXML. Un reverse proxy a abandonné en attendant la réponse du serveur cible. Souvent un timeout trop court côté proxy.

    Source: cXML Reference Guide v1.2.070, §3.1.9 (transport-level)

Pièges fréquents hors codes Status

15 erreurs récurrentes en prod qui ne remontent pas comme codes Status, mais qui font perdre du temps aux devs. Retour d'expérience terrain.

  • DTD inaccessible ou validation externe désactivée

    structure xxe

    Le récepteur ne peut pas télécharger l'URL du DTD déclarée dans le DOCTYPE, ou refuse la résolution externe pour des raisons XXE.

    Détails, symptômes et fix →

    L'XML cXML déclare typiquement `<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.070/cXML.dtd">`. Si le récepteur a une politique XXE stricte (ce qui est la bonne pratique sécurité), il refusera de résoudre cette URL externe. Symptôme : le parser XML lève une erreur de validation sans message clair.

    Symptômes

    • 400 Bad Request ou 406 Not Acceptable sans détail clair
    • Logs côté récepteur mentionnant 'XXE blocked' ou 'external entity'
    • Timeout HTTP sur le récepteur en attendant la résolution DTD

    Fix

    Héberger le DTD localement côté récepteur (catalogue XML resolver). Configurer le parser pour ne PAS résoudre les entités externes. Si nécessaire, retirer la déclaration DOCTYPE et valider via XSD-équivalent.

  • Encodage déclaré ≠ encodage réel des bytes

    encoding i18n

    Le document déclare `encoding="UTF-8"` dans le prologue XML mais les bytes sont en ISO-8859-1 (ou inverse). Casse les caractères accentués FR/DE.

    Détails, symptômes et fix →

    Symptôme typique : des `é` deviennent `é` ou `?` côté récepteur. Cause courante : sérialisation Java/PHP qui n'aligne pas explicitement le charset avec le content-type HTTP, ou copier-coller entre éditeurs avec encodage différent.

    Symptômes

    • Caractères accentués corrompus dans Description/LongName côté buyer
    • Validation DTD échouée sans message clair sur l'encoding
    • 406 Not Acceptable avec mention parsing

    Fix

    Forcer UTF-8 partout : sérialisation XML, Content-Type HTTP (`text/xml; charset=UTF-8`), connexion DB, lecture template. Tester avec un mot-clé contenant é/à/ü.

  • payloadID non unique

    idempotence replay

    Format recommandé : `timestamp.process.counter@hostname.tld`. Réutiliser le même payloadID = rejet silencieux ou 409 Conflict.

    Détails, symptômes et fix →

    Ariba (et la plupart des hubs) considèrent qu'une requête avec un payloadID déjà vu est un replay et le drop pour éviter la double facturation/commande. Aucun mécanisme retry ne récupère ça - il faut un nouveau payloadID.

    Symptômes

    • 409 Conflict sur des retries après un échec partiel
    • Commande visible côté supplier mais non côté buyer
    • Pas d'erreur visible mais commande jamais reçue

    Fix

    Générer un payloadID strictement unique à chaque envoi (UUID + timestamp + counter atomique). NE JAMAIS retry sans changer le payloadID.

  • Clock skew - horloge décalée de plus de 5 minutes

    security replay

    L'attribut `timestamp` ISO 8601 du `<cXML>` racine décalé de plus de 5 min par rapport à l'horloge du destinataire = rejet anti-replay.

    Détails, symptômes et fix →

    Beaucoup de hubs et buyers (Ariba inclus) appliquent une fenêtre de tolérance horloge de ±5 min pour rejeter les messages potentiellement rejoués. Si votre serveur n'est pas synchronisé NTP, vous pouvez dériver de plusieurs minutes en quelques jours.

    Symptômes

    • 401 Unauthorized ou 400 Bad Request sans cause évidente
    • Erreur intermittente qui apparaît/disparaît selon la dérive horloge
    • Tests qui passent au sandbox et qui échouent en prod (env différents)

    Fix

    Installer et activer NTP (systemd-timesyncd, chrony, ntpd) sur votre serveur. Vérifier la dérive avec `timedatectl status`. Aligner aussi le fuseau (UTC recommandé).

  • SharedSecret avec espaces ou newlines invisibles

    auth

    Copier-coller depuis un email ajoute des `\r\n` ou espaces. Le SharedSecret transmis est techniquement différent du SharedSecret stocké par le buyer = 401 Unauthorized.

    Détails, symptômes et fix →

    C'est THE source d'erreur sur les 401. Le SharedSecret affiché dans Ariba a souvent un copier-coller récalcitrant : caractères whitespace invisibles, ou tabulations. Le buyer compare byte-par-byte.

    Symptômes

    • 401 systématique
    • Re-saisie manuelle du SharedSecret résout le problème
    • Hexdump du SharedSecret stocké montre des octets non-printables

    Fix

    TRIM systématique avant comparaison ou envoi. Hexdump pour traquer les caractères : `hexdump -C <<< "$SHARED_SECRET"`. Re-saisir manuellement plutôt que copier-coller.

  • BuyerCookie modifié ou perdu entre Setup et OrderMessage

    punchout state

    Le supplier DOIT retourner EXACTEMENT le BuyerCookie reçu au PunchOutSetupRequest dans le PunchOutOrderMessage. Différent = panier orphelin côté buyer.

    Détails, symptômes et fix →

    Le BuyerCookie est l'identifiant de session côté buyer. Il permet à Ariba/Coupa de retrouver la session de l'acheteur. Si vous le modifiez (par exemple parce que vous URL-encodez la valeur), le buyer ne retrouve plus la session.

    Symptômes

    • 412 Precondition Failed
    • Panier disparu côté buyer ('session expired')
    • Pas d'erreur HTTP mais l'acheteur revient sur une page d'erreur générique

    Fix

    Stocker le BuyerCookie tel quel en session supplier (Magento session, Redis, etc.), le rejouer textuellement dans le PunchOutOrderMessage. Aucun encoding, aucune transformation.

  • Quantity en décimal avec virgule (locale FR)

    format locale

    La locale FR sérialise `1,5` au lieu de `1.5` pour les nombres décimaux. cXML attend le point. Parse error côté buyer.

    Détails, symptômes et fix →

    Bug récurrent en Java/PHP/.NET avec la locale système configurée en français. La méthode `toString()` ou `format()` par défaut utilise la virgule. Le buyer parse en double et plante.

    Symptômes

    • 400 Bad Request ou 406 Not Acceptable au parse du PunchOutOrderMessage
    • Erreur 'NumberFormatException' côté Ariba

    Fix

    Forcer `Locale.US` (Java), `setlocale(LC_NUMERIC, 'C')` (PHP), ou `CultureInfo.InvariantCulture` (.NET) pour TOUTES les sérialisations XML.

  • Confusion entre From et Sender dans le Header

    auth identity

    `From` = origine logique du message (qui a créé le doc). `Sender` = entité technique qui transmet (peut être un hub ou middleware). Mauvais mapping = 401.

    Détails, symptômes et fix →

    Le Header cXML contient toujours `<From>`, `<To>` et `<Sender>`. Beaucoup de devs mettent la même identité partout, mais ça casse quand il y a un middleware intermédiaire. Le SharedSecret est attaché au `<Sender>`, pas au `<From>`.

    Symptômes

    • 401 Unauthorized malgré un SharedSecret correct
    • Documentation buyer mentionne explicitement les 3 rôles distincts

    Fix

    Lire la doc PunchOut Configuration du buyer (Ariba: 'Configuring PunchOut Sites'), respecter le mapping From/To/Sender exact. SharedSecret toujours dans `<Sender><Credential>`.

  • Content-Type HTTP incorrect ou manquant

    transport

    Le header HTTP `Content-Type` doit être `text/xml; charset=UTF-8` ou `application/xml`. `text/plain` ou absent = rejet.

    Détails, symptômes et fix →

    Certains clients HTTP par défaut envoient `text/plain` ou rien du tout. Ariba refuse de parser sans un content-type XML explicite. Bug typique en utilisant un client HTTP minimaliste sans configuration.

    Symptômes

    • 400 Bad Request avec Status mentionnant le content-type
    • Aucune réponse cXML, juste une erreur HTTP
    • Curl en debug montre le mauvais header

    Fix

    Setter explicitement `Content-Type: text/xml; charset=UTF-8` dans tous les appels HTTP. Vérifier avec `curl -v` ou un proxy de debug.

  • BrowserFormPost URL en HTTP au lieu de HTTPS

    transport security

    Ariba refuse les BrowserFormPost en HTTP (interdit en prod depuis ~2018). HTTPS obligatoire avec certificat valide.

    Détails, symptômes et fix →

    Le BrowserFormPost est l'URL où l'acheteur sera redirigé après le retour du panier. Ariba (et la plupart des grands buyers) refuse les URLs en HTTP pour prévenir les MITM avec interception des données panier.

    Symptômes

    • Setup PunchOut OK mais retour panier impossible
    • Erreur côté Ariba mentionnant 'insecure URL'

    Fix

    Passer toutes les URLs cXML (PunchOutSetupResponse `<URL>`, BrowserFormPost) en HTTPS avec certificat Let's Encrypt ou équivalent. Pas de self-signed.

  • Certificat SSL self-signed, expiré, ou chaîne incomplète

    transport security

    Ariba/Coupa refusent les self-signed et les chaînes incomplètes. Certificat doit inclure les intermédiaires.

    Détails, symptômes et fix →

    Erreur courante chez les suppliers : nginx ou Apache servent le certificat leaf sans les intermédiaires (`fullchain.pem` au lieu de `cert.pem`). Le client (Ariba) ne peut pas valider la chaîne et coupe la connexion.

    Symptômes

    • 550 Unable to reach cXML server
    • TLS handshake failed côté client
    • openssl s_client mentionne 'unable to verify chain'

    Fix

    Utiliser `fullchain.pem` (ou équivalent) qui contient leaf + intermédiaires. Renouveler avant expiration (Let's Encrypt = automatique). Vérifier avec https://www.ssllabs.com/ssltest/

  • Reverse proxy 502/504 - timeout trop court

    transport

    Nginx/Apache devant votre app coupe avant la réponse cXML (timeout 60s par défaut). Le buyer voit un 502/504 HTTP, pas un Status cXML.

    Détails, symptômes et fix →

    Le traitement d'un OrderRequest en cXML peut prendre plusieurs secondes côté supplier (validation catalogue, vérification stock, écriture DB). Si le reverse proxy a un `proxy_read_timeout` trop court, il coupe la connexion avant la réponse, et le buyer voit un transport error.

    Symptômes

    • Le buyer reporte un 502 ou 504 HTTP
    • L'app supplier a bien traité l'OrderRequest (visible dans les logs Magento)
    • Les requêtes plus simples (Ping, ProfileResponse) marchent

    Fix

    Augmenter `proxy_read_timeout` (nginx) ou `Timeout` (Apache) à 300s minimum pour les endpoints cXML. Optimiser le traitement supplier pour finir sous 30s.

  • Identity sensible à la casse - ANID en majuscules strictes

    auth identity

    Ariba compare l'attribut `identity` en byte exact. ANID `AN01234567890` ≠ `an01234567890`. Idem pour les DUNS.

    Détails, symptômes et fix →

    Les identifiants Ariba Network (ANID) commencent toujours par `AN` en majuscules suivi de chiffres. Beaucoup de bases de données normalisent en lowercase au stockage. Si vous envoyez en lowercase, Ariba ne trouve pas l'identité.

    Symptômes

    • 401 Unauthorized avec le bon SharedSecret
    • La copie exacte depuis le portail Ariba marche, mais le copier-coller via DB échoue

    Fix

    Stocker les ANID/DUNS en majuscules strictes. Désactiver la normalisation lowercase côté DB pour ces champs. Tester avec un hexdump si nécessaire.

  • CDATA mal échappé dans Description ou LongName

    structure format

    HTML embarqué dans Description (caractères `<`, `>`, `&`) casse le parser si non encapsulé en CDATA ou non échappé.

    Détails, symptômes et fix →

    Les Description PunchOut contiennent souvent du HTML formaté (bullets, gras). Sans encapsulation CDATA ou échappement des entités XML, le parser cXML voit `<b>` comme une balise XML et plante.

    Symptômes

    • 406 Not Acceptable au parse
    • Erreur côté buyer mentionnant 'unexpected element'

    Fix

    Soit encapsuler le HTML dans `<![CDATA[...]]>`, soit échapper les caractères : `&lt;`, `&gt;`, `&amp;`. Tester avec un produit dont la description contient du HTML.

  • `deploymentMode="test"` oublié en prod

    environment

    L'attribut `deploymentMode` du Request indique au buyer si c'est du test ou de la prod. Oublié à `test` en prod = routing vers l'env test du buyer, échec silencieux.

    Détails, symptômes et fix →

    Pendant le dev/QA, on hardcode souvent `deploymentMode="test"`. À la mise en prod, on oublie de basculer en `production`. Le buyer route vers son environnement de test (différents endpoints, différentes credentials) et ne reçoit pas les commandes en prod.

    Symptômes

    • Commandes 'envoyées avec succès' côté supplier
    • Buyer ne reçoit aucune commande en prod
    • Tout fonctionnait au sandbox

    Fix

    Toujours setter `deploymentMode` via variable d'environnement (`production` par défaut). Inclure dans la checklist de release.

Pour aller plus loin

Sources

Cette référence est sourcée du cXML Reference Guide v1.2.070, publié par SAP Ariba le 16/05/2026, sections §3.1.9 (codes Status généraux), §3.1.10 (codes upload de catalogue) et §23.2.2 (codes signature numérique).

Les sections "Causes typiques", "Checklist debug" et "Fix typique" sont des observations terrain en intégration cXML (patterns récurrents observés chez Ariba, Coupa, Oracle, Jaggaer, etc.), pas des éléments de la spec officielle. Elles sont clairement étiquetées comme telles dans l'interface.