Skip to content
Gatebold

cXML Reference

cXML error codes - complete reference.

36 official Status codes (200, 401, 406, 450, 475, 500, etc.) sourced from the cXML Reference Guide v1.2.070. Plus 15 common non-code pitfalls (encoding, payloadID, SharedSecret, etc.). Causes, debug, fix.

This page lists all cXML Status codes documented in the cXML Reference Guide version 1.2.070 .

HTTP vs cXML: the 2 error levels in a cXML response

A buyer response contains two distinct codes in two different places: the HTTP code in the headers, and the cXML code in the XML body. This page primarily documents cXML codes, and lists separately the HTTP transport codes (404, 502, 504, etc.) that are often confused with them. 

# What you receive when you POST to a cXML buyer:

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

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

In this example, the HTTP transport succeeded (the message reached the buyer) but the cXML failed (the buyer rejected authentication). The classic trap: a dev sees HTTP 200 in their logs and concludes "everything is fine" without parsing the XML - even though the order was never accepted.

cXML codes reference

36 official Status codes + 15 non-code pitfalls. Sourced from cXML Reference Guide v1.2.070 (May 16, 2026).

cXML 1.2.070
Severity : Info success, no action needed Permanent fix the request, do not retry Transient (retry) temporary, retry with backoff
Filter

Success codes (2xx)

  • cXML 200 OK

    Info

    The server was able to execute the request or deliver it to the final recipient. The returned Response might contain application warnings or errors; cXML 200 only signals that the cXML protocol itself succeeded, not subsequent application errors.

    Details, causes and fix →

    Typical causes (field experience)

    • Normal success path for PunchOutSetup, PunchOutOrderMessage, ConfirmationRequest, etc.

    XML example 

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

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 201 Accepted

    Info

    The request has been accepted for forwarding by an intermediate hub, or has been accepted by its ultimate destination and not yet examined. The client should expect a later StatusUpdateRequest.

    Details, causes and fix →

    Typical causes (field experience)

    • OrderRequest sent through Ariba Network in async mode
    • Document accepted for deferred processing on the supplier side

    Debug checklist

    • Verify reception of the subsequent StatusUpdateRequest (can take minutes to hours)
    • Log the payloadID to correlate with the StatusUpdate

    Related codes

    280 281

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 204 No Content

    Info

    All Request information was valid and recognized. The server has no Response data of the type requested. In a PunchOutOrderMessage, this status indicates the PunchOut session ended without change to the shopping cart.

    Details, causes and fix →

    Typical causes (field experience)

    • User exited the PunchOut catalogue without adding anything to the cart (cancel)
    • Legitimate async request with no return payload

    Related codes

    200 280

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 211 OK

    Info

    Buyers can use this status code to broadcast informational messages to suppliers (holiday schedules, production facility closures, completion of activities such as planning run completion, etc.). Does not imply a required supplier action.

  • cXML 280 Forwarded

    Info

    The request has been forwarded by an intermediate hub. The client will receive at least one more status update. This can mean the request was delivered to another intermediary (replying 201) or to the final recipient.

    Details, causes and fix →

    Typical causes (field experience)

    • Routing through Ariba Network that forwards to another hub
    • Transit via enterprise middleware

    Related codes

    201 281

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 281 Forwarded (unreliable transport)

    Info

    The request has been forwarded by an intermediate hub using an unreliable transport (such as email). Status updates might not arrive; their absence is not necessarily a problem.

    Details, causes and fix →

    Typical causes (field experience)

    • Email/fax routing via Ariba Network for a supplier not configured for real-time cXML

    Related codes

    280

    Source: cXML Reference Guide v1.2.070, §3.1.9

Generic permanent errors (4xx)

  • cXML 400 Bad Request

    Permanent

    Request unacceptable to the server, although it parsed correctly. This is a content-level error, not a syntax error (see 406 for parse failures).

    Details, causes and fix →

    Typical causes (field experience)

    • BuyerCookie missing or invalid in a PunchOutOrderMessage
    • Attribute value outside enum (operation, type, etc.)
    • Reference to a server-side object that does not exist

    Debug checklist

    • Log the Status element text content (often a usable hint)
    • Compare the sent XML with a known-good PunchOutOrderMessage
    • Verify required attributes on all elements

    Typical fix

    Read the Status message returned by the server, fix the offending element or attribute, retest.

    XML example 

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

    Related codes

    406 412 417

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 401 Unauthorized

    Permanent

    Credentials provided in the Request (the Sender element) were not recognized by the server. The #1 cause of cXML integration failure.

    Details, causes and fix →

    Typical causes (field experience)

    • SharedSecret pasted with invisible spaces or trailing newlines
    • Wrong Credential domain (e.g. NetworkID instead of DUNS)
    • Case-sensitive Identity not respected (Ariba ANID strictly uppercase)
    • Sender configured for a different environment (test vs prod)

    Debug checklist

    • Always trim SharedSecret before sending
    • Hex-dump the stored SharedSecret to catch invisible characters
    • Compare letter-by-letter the received `domain` and `identity` with the supplier config in Ariba Network
    • Verify From, Sender and Credential point to the correct entity

    Typical fix

    Re-sync the SharedSecret with the buyer through their portal. If the error persists, verify exact alignment of From/Sender/Credential fields.

    Related codes

    403 412

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 402 Payment Required

    Permanent

    This Request must include a complete Payment element. Rarely encountered in PunchOut integrations in practice.

    Details, causes and fix →

    Typical causes (field experience)

    • Buyer overdue payment to Ariba (hub case)
    • Incomplete PCard flow

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 403 Forbidden

    Permanent

    The user has insufficient privileges to execute this Request. The identity is correctly recognized (otherwise 401) but the action is forbidden.

    Details, causes and fix →

    Typical causes (field experience)

    • Buyer account disabled
    • Document type not allowed for this identity (e.g. InvoiceDetailRequest without permission)
    • Permission configuration on the supplier or buyer side

    Debug checklist

    • Check the buyer account status (active/suspended)
    • Check the document type accepted for this supplier

    Related codes

    401

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 406 Not Acceptable

    Permanent

    Request unacceptable to the server, likely due to a parsing failure. Typically raised when XML is not DTD-compliant.

    Details, causes and fix →

    Typical causes (field experience)

    • Malformed XML (unclosed tag, invalid order)
    • Missing required element
    • Attribute value outside DTD-declared enum
    • Encoding differs from declaration in <?xml ?>
    • DTD URL unreachable while validation is enabled

    Debug checklist

    • Validate XML against the official cXML 1.2.070 DTD (our free cXML validator does this)
    • Verify the <!DOCTYPE> declaration at the top
    • Inspect the Status element text content (parser error often included)

    Typical fix

    Use our cXML validator to pinpoint the offending element/attribute, then fix.

    XML example 

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

    Related codes

    400 412

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 409 Conflict

    Permanent

    The current state of the server or its internal data prevented the (update) operation request. An identical Request is unlikely to succeed in the future unless another operation has executed in between.

    Details, causes and fix →

    Typical causes (field experience)

    • Duplicate payloadID (replay of an already-received message)
    • Attempt to modify an order already confirmed/shipped
    • Attempt to create an object that already exists

    Debug checklist

    • Verify payloadID uniqueness (recommended format: `timestamp.process.counter@domain`)
    • Trace the order state on the buyer side before retrying

    Typical fix

    Regenerate a unique payloadID on every send. DO NOT mechanically retry on 409 - the conflict will not resolve itself.

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 412 Precondition Failed

    Permanent

    A precondition of the Request was not met. For example, a PunchOut session appropriate for a PunchOutSetupRequest edit. Typically implies the client ignored some portion of a previous server transmission (e.g. operationAllowed attribute).

    Details, causes and fix →

    Typical causes (field experience)

    • BuyerCookie missing or modified between Setup and OrderMessage
    • 'edit' operation attempted on a session without edit permission
    • operationAllowed of PunchOutOrderMessageHeader ignored

    Typical fix

    Preserve the BuyerCookie received at Setup and replay it identically. Honour operationAllowed.

    Related codes

    400 401

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 417 Expectation Failed

    Permanent

    Request implied a resource condition that was not met. One example: a SupplierDataRequest asking for information about a supplier unknown to the server. This status might imply lost information at the client or server.

  • cXML 450 Not Implemented

    Permanent

    The server does not implement the particular Request. For example, PunchOutSetupRequest or the requested operation might not be supported. This status normally implies the client has ignored the server's profile.

    Details, causes and fix →

    Typical causes (field experience)

    • Document type not supported by the supplier (e.g. OrderRequest sent to a PunchOut-only supplier)
    • Operation `edit`/`inspect` sent to a supplier that does not support it
    • Declared cXML version not supported

    Debug checklist

    • Check supplier capabilities via its ProfileResponse
    • Consult the buyer documentation on supported PunchOut operations

    Typical fix

    Use a supported document type or ask the supplier to implement the new operation.

    Source: cXML Reference Guide v1.2.070, §3.1.9

Digital signatures (475-477)

  • cXML 475 Signature Required

    Permanent

    The receiver is unwilling to accept the document because it does not have a digital signature. Not to be confused with a generic PunchOut error.

    Details, causes and fix →

    Typical causes (field experience)

    • The buyer requires signed messages (hardened security configuration)
    • Unsigned InvoiceDetailRequest sent to a buyer that mandates signatures

    Typical fix

    Implement cXML signing (signatureVersion='1.0' and XML signature per section 23 of the Reference Guide).

    Related codes

    476 477

    Source: cXML Reference Guide v1.2.070, §23.2.2

  • cXML 476 Signature Verification Failed

    Permanent

    The receiver is unable to validate the signature, possibly because the document was altered in transit, or the receiver does not support one or more algorithms used in the signature.

    Details, causes and fix →

    Typical causes (field experience)

    • Document modified by middleware (proxy re-encoding the XML)
    • Signature algorithm not supported (e.g. SHA-512)
    • Certificate expired or revoked

    Typical fix

    Verify the document is not modified in transit. Align the algorithm with what the buyer supports (often RSA-SHA256).

    Related codes

    475 477

    Source: cXML Reference Guide v1.2.070, §23.2.2

  • cXML 477 Signature Unacceptable

    Permanent

    The signature is technically valid, but not acceptable to the receiver for some other reason. The signature or certificate policies may be unacceptable, the type of certificate used may be unacceptable, or there may be some other problem.

    Details, causes and fix →

    Typical causes (field experience)

    • Self-signed certificate not accepted
    • Certificate authority not whitelisted by the buyer
    • Signature policy not compliant (e.g. insufficient key length)

    Related codes

    475 476

    Source: cXML Reference Guide v1.2.070, §23.2.2

Catalog upload (461-470, 499, 561-563)

  • cXML 461 Bad Commodity Code

    Permanent

    The commodity code assigned to the catalog is invalid.

    Details, causes and fix →

    Typical causes (field experience)

    • Malformed UNSPSC code (wrong number of digits)
    • Commodity code unknown to the buyer

    Source: cXML Reference Guide v1.2.070, §3.1.10

  • cXML 462 Notification Error

    Permanent

    No notification method (email or URL) provided for the catalog upload result.

  • cXML 463 Bad Catalog Format

    Permanent

    The transmitted zip file is invalid. Content is not a valid zip or is corrupted.

  • cXML 464 Bad Catalog

    Permanent

    No catalog is attached, or more than one is attached. Exactly one catalog must be present per upload.

  • cXML 465 Duplicate Catalog Name

    Permanent

    The catalog name already exists on the buyer side. Use a unique name for a new version or update the existing one explicitly.

  • cXML 466 No Catalog to Update

    Permanent

    The catalog to be updated does not exist on the buyer side.

  • cXML 467 Publish Not Allowed

    Permanent

    You attempted to publish a catalog that was not previously published. First publication follows a different workflow.

  • cXML 468 Catalog Too Large

    Permanent

    The uploaded file size exceeds the 4 MB limit. Zip the catalog before uploading.

    Details, causes and fix →

    Typical fix

    Compress the catalog to .zip before upload, or split the catalog into multiple partial publications.

    Source: cXML Reference Guide v1.2.070, §3.1.10

  • cXML 469 Bad Catalog Extension

    Permanent

    The catalog filename must have a .cif, .xml or .zip extension.

  • cXML 470 Catalog Has Errors

    Permanent

    The catalog content contains errors (HasErrors validation). The buyer typically returns error details in the response payload.

  • cXML 499 Document Size Error

    Permanent

    The cXML document is too large to be processed by the recipient.

    Details, causes and fix →

    Typical fix

    Split into multiple smaller documents or compress via HTTP gzip if supported.

    Source: cXML Reference Guide v1.2.070, §3.1.10

  • cXML 561 Too Many Catalogs

    Transient (retry)

    You cannot upload more than a specific number of catalogs per hour (buyer-side rate limit).

    Details, causes and fix →

    Typical fix

    Space out uploads. Implement a supplier-side queue respecting the buyer rate limit.

    Source: cXML Reference Guide v1.2.070, §3.1.10

  • cXML 562 Publish Disabled

    Transient (retry)

    Catalog publishing is temporarily unavailable due to scheduled maintenance. The buyer specifies the back-online date/time.

  • cXML 563 Catalog Validating

    Transient (retry)

    You attempted to update a catalog before validation finished on the previous version.

    Details, causes and fix →

    Typical fix

    Wait for validation completion (completion notification) before pushing a new version.

    Source: cXML Reference Guide v1.2.070, §3.1.10

Transient errors (5xx)

  • cXML 500 Internal Server Error

    Transient (retry)

    The server was unable to complete the Request. Generic recipient-side error, retryable.

    Details, causes and fix →

    Typical causes (field experience)

    • Uncaught exception on the recipient side
    • Database unavailable
    • Application bug on the server side

    Debug checklist

    • Check the Status element text content (often contains the error detail)
    • Log the payloadID for investigation on the supplier or hub side

    Typical fix

    Retry with exponential backoff. If persistent, open a ticket with the recipient including the payloadID.

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 550 Unable to reach cXML server

    Transient (retry)

    Unable to reach the next cXML server to complete a transaction requiring upstream connections. An intermediate hub can return this code when a supplier site is unreachable.

    Details, causes and fix →

    Typical causes (field experience)

    • Supplier endpoint down or timing out
    • Broken Ariba Network routing configuration
    • Expired SSL certificate on the supplier side

    Debug checklist

    • Test the supplier endpoint directly (curl)
    • openssl s_client to verify the certificate
    • Ping DNS, check the firewall

    Related codes

    551 560

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 551 Unable to forward request

    Transient (retry)

    Unable to forward request because of supplier misconfiguration. For example, an intermediate hub failed to authenticate to a supplier. Clients cannot rectify this error, but it might be resolved before the client retries.

    Details, causes and fix →

    Typical causes (field experience)

    • Hub-to-supplier auth broken (stale SharedSecret on the supplier side)
    • Supplier endpoint URL changed without updating the hub config

    Typical fix

    Supplier side: verify the authentication config in Ariba Network. The client should wait for resolution.

    Related codes

    550

    Source: cXML Reference Guide v1.2.070, §3.1.9

  • cXML 560 Temporary server error

    Transient (retry)

    For example, a server might be down for maintenance. The client should retry later.

    Details, causes and fix →

    Typical fix

    Retry with exponential backoff. Spec recommends 10 retries at 1-hour frequency, minimum 6-hour window.

    Source: cXML Reference Guide v1.2.070, §3.1.9

HTTP transport errors (non-cXML)

These HTTP codes are NOT cXML codes, but are routinely confused with them. Treat as transient transport errors.

  • HTTP 404 Not Found

    Transport

    HTTP transport error, NOT a cXML code. The target endpoint URL is unknown to the server. Treat as a transient error (retry after verifying the URL).

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

  • HTTP 408 Request Timeout

    Transport

    HTTP transport error, NOT a cXML code. The server did not receive the complete request in time. Treat as a transient error.

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

  • HTTP 502 Bad Gateway

    Transport

    HTTP transport error, NOT a cXML code. An intermediate reverse proxy could not reach the target server. Retry, verify proxy timeouts.

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

  • HTTP 503 Service Unavailable

    Transport

    HTTP transport error, NOT a cXML code. Service temporarily unavailable (maintenance, rate limit, overload). Retry with backoff.

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

  • HTTP 504 Gateway Timeout

    Transport

    HTTP transport error, NOT a cXML code. An intermediate proxy gave up while waiting for the target server. Often a proxy-side timeout too short.

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

Common pitfalls outside Status codes

15 recurring production errors that don't surface as Status codes but routinely waste developer time. Field experience.

  • DTD unreachable or external validation disabled

    structure xxe

    The recipient cannot download the DTD URL declared in the DOCTYPE, or refuses external resolution due to XXE security policy.

    Details, symptoms and fix →

    cXML XML typically declares `<!DOCTYPE cXML SYSTEM "http://xml.cXML.org/schemas/cXML/1.2.070/cXML.dtd">`. Recipients with a strict XXE policy (which is good security practice) will refuse to resolve this external URL. Symptom: XML parser raises a validation error without a clear message.

    Symptoms

    • 400 Bad Request or 406 Not Acceptable without clear detail
    • Recipient logs mention 'XXE blocked' or 'external entity'
    • HTTP timeout on the recipient waiting for DTD resolution

    Fix

    Host the DTD locally on the recipient side (XML catalog resolver). Configure the parser to NOT resolve external entities. If needed, drop the DOCTYPE declaration and validate via XSD-equivalent.

  • Declared encoding does not match actual bytes

    encoding i18n

    The document declares `encoding="UTF-8"` in the XML prolog but bytes are ISO-8859-1 (or vice versa). Breaks accented characters in FR/DE.

    Details, symptoms and fix →

    Typical symptom: `é` becomes `é` or `?` on the recipient side. Common cause: Java/PHP serialization that does not explicitly align charset with HTTP content-type, or copy-paste between editors with different encodings.

    Symptoms

    • Corrupted accented characters in Description/LongName on buyer side
    • DTD validation fails without clear encoding message
    • 406 Not Acceptable with parsing mention

    Fix

    Force UTF-8 everywhere: XML serialization, HTTP Content-Type (`text/xml; charset=UTF-8`), DB connection, template reading. Test with a keyword containing é/à/ü.

  • Non-unique payloadID

    idempotence replay

    Recommended format: `timestamp.process.counter@hostname.tld`. Reusing the same payloadID = silent reject or 409 Conflict.

    Details, symptoms and fix →

    Ariba (and most hubs) treat a request with an already-seen payloadID as a replay and drop it to prevent double billing/ordering. No retry mechanism recovers this - a new payloadID is required.

    Symptoms

    • 409 Conflict on retries after partial failure
    • Order visible on supplier side but not on buyer side
    • No visible error but order never received

    Fix

    Generate a strictly unique payloadID on every send (UUID + timestamp + atomic counter). NEVER retry without changing the payloadID.

  • Clock skew - clock off by more than 5 minutes

    security replay

    The ISO 8601 `timestamp` attribute on the `<cXML>` root, off by more than 5 minutes from the recipient clock, triggers anti-replay rejection.

    Details, symptoms and fix →

    Many hubs and buyers (including Ariba) apply a ±5 min clock tolerance window to reject potentially-replayed messages. If your server is not NTP-synchronized, you can drift by minutes within days.

    Symptoms

    • 401 Unauthorized or 400 Bad Request without obvious cause
    • Intermittent error appearing/disappearing with clock drift
    • Tests pass in sandbox, fail in prod (different environments)

    Fix

    Install and enable NTP (systemd-timesyncd, chrony, ntpd) on your server. Verify drift with `timedatectl status`. Align timezone too (UTC recommended).

  • SharedSecret with invisible spaces or newlines

    auth

    Copy-paste from an email adds `\r\n` or spaces. The transmitted SharedSecret differs technically from the buyer-stored one = 401 Unauthorized.

    Details, symptoms and fix →

    This is THE source of 401 errors. The SharedSecret displayed in Ariba often has stubborn copy-paste: invisible whitespace, tabs. The buyer compares byte-by-byte.

    Symptoms

    • Systematic 401
    • Manual re-typing of SharedSecret resolves the issue
    • Hexdump of stored SharedSecret shows non-printable bytes

    Fix

    Always trim before comparing or sending. Hexdump to track characters: `hexdump -C <<< "$SHARED_SECRET"`. Re-type manually rather than copy-paste.

  • BuyerCookie modified or lost between Setup and OrderMessage

    punchout state

    The supplier MUST return EXACTLY the BuyerCookie received at PunchOutSetupRequest in the PunchOutOrderMessage. Different = orphan cart on buyer side.

    Details, symptoms and fix →

    The BuyerCookie is the buyer-side session identifier. It allows Ariba/Coupa to retrieve the requisitioner's session. If you modify it (e.g. URL-encode the value), the buyer cannot retrieve the session.

    Symptoms

    • 412 Precondition Failed
    • Cart vanished on buyer side ('session expired')
    • No HTTP error but requisitioner lands on a generic error page

    Fix

    Store the BuyerCookie as-is in the supplier session (Magento session, Redis, etc.), replay it verbatim in the PunchOutOrderMessage. No encoding, no transformation.

  • Quantity in decimal with comma (FR locale)

    format locale

    FR locale serializes `1,5` instead of `1.5` for decimal numbers. cXML expects the dot. Parse error on buyer side.

    Details, symptoms and fix →

    Recurring bug in Java/PHP/.NET with system locale set to French. Default `toString()` or `format()` uses the comma. The buyer parses as double and crashes.

    Symptoms

    • 400 Bad Request or 406 Not Acceptable at PunchOutOrderMessage parse
    • 'NumberFormatException' error on Ariba side

    Fix

    Force `Locale.US` (Java), `setlocale(LC_NUMERIC, "C")` (PHP), or `CultureInfo.InvariantCulture` (.NET) for ALL XML serializations.

  • Confusion between From and Sender in the Header

    auth identity

    `From` = logical origin of the message (who created the doc). `Sender` = technical entity transmitting (can be a hub or middleware). Wrong mapping = 401.

    Details, symptoms and fix →

    The cXML Header always contains `<From>`, `<To>` and `<Sender>`. Many devs put the same identity everywhere, but this breaks when there is an intermediate middleware. The SharedSecret is attached to `<Sender>`, not `<From>`.

    Symptoms

    • 401 Unauthorized despite a correct SharedSecret
    • Buyer documentation explicitly mentions the 3 distinct roles

    Fix

    Read the buyer's PunchOut Configuration doc (Ariba: 'Configuring PunchOut Sites'), respect the exact From/To/Sender mapping. SharedSecret always in `<Sender><Credential>`.

  • Wrong or missing HTTP Content-Type

    transport

    HTTP `Content-Type` header must be `text/xml; charset=UTF-8` or `application/xml`. `text/plain` or missing = rejection.

    Details, symptoms and fix →

    Some HTTP clients default to `text/plain` or nothing at all. Ariba refuses to parse without an explicit XML content-type. Typical bug when using a minimal HTTP client without configuration.

    Symptoms

    • 400 Bad Request with Status mentioning content-type
    • No cXML response, just HTTP error
    • Curl debug shows the wrong header

    Fix

    Explicitly set `Content-Type: text/xml; charset=UTF-8` on all HTTP calls. Verify with `curl -v` or a debug proxy.

  • BrowserFormPost URL in HTTP instead of HTTPS

    transport security

    Ariba refuses HTTP BrowserFormPost (forbidden in production since ~2018). HTTPS mandatory with valid certificate.

    Details, symptoms and fix →

    BrowserFormPost is the URL where the requisitioner is redirected after cart return. Ariba (and most major buyers) refuses HTTP URLs to prevent MITM with cart data interception.

    Symptoms

    • PunchOut setup OK but cart return impossible
    • Ariba-side error mentioning 'insecure URL'

    Fix

    Switch all cXML URLs (PunchOutSetupResponse `<URL>`, BrowserFormPost) to HTTPS with Let's Encrypt or equivalent certificate. No self-signed.

  • Self-signed, expired, or incomplete chain SSL certificate

    transport security

    Ariba/Coupa refuse self-signed certificates and incomplete chains. Certificates must include intermediates.

    Details, symptoms and fix →

    Common supplier error: nginx or Apache serve the leaf certificate without intermediates (`fullchain.pem` instead of `cert.pem`). The client (Ariba) cannot validate the chain and drops the connection.

    Symptoms

    • 550 Unable to reach cXML server
    • TLS handshake failed on the client side
    • openssl s_client mentions 'unable to verify chain'

    Fix

    Use `fullchain.pem` (or equivalent) containing leaf + intermediates. Renew before expiration (Let's Encrypt = automatic). Verify with https://www.ssllabs.com/ssltest/

  • Reverse proxy 502/504 - timeout too short

    transport

    Nginx/Apache in front of your app cuts before the cXML response (60s default timeout). The buyer sees an HTTP 502/504, not a cXML Status.

    Details, symptoms and fix →

    Processing an OrderRequest in cXML can take several seconds on the supplier side (catalog validation, stock check, DB write). If the reverse proxy has too short a `proxy_read_timeout`, it cuts the connection before the response, and the buyer sees a transport error.

    Symptoms

    • The buyer reports an HTTP 502 or 504
    • The supplier app actually processed the OrderRequest (visible in Magento logs)
    • Simpler requests (Ping, ProfileResponse) work

    Fix

    Increase `proxy_read_timeout` (nginx) or `Timeout` (Apache) to 300s minimum for cXML endpoints. Optimize supplier processing to finish under 30s.

  • Case-sensitive Identity - strictly uppercase ANID

    auth identity

    Ariba compares the `identity` attribute byte-exact. ANID `AN01234567890` ≠ `an01234567890`. Same for DUNS.

    Details, symptoms and fix →

    Ariba Network IDs (ANID) always start with `AN` in uppercase followed by digits. Many databases normalize to lowercase on storage. If you send lowercase, Ariba does not find the identity.

    Symptoms

    • 401 Unauthorized with the correct SharedSecret
    • Exact copy from the Ariba portal works, but copy via DB fails

    Fix

    Store ANIDs/DUNS in strict uppercase. Disable lowercase normalization on the DB side for these fields. Test with hexdump if necessary.

  • CDATA improperly escaped in Description or LongName

    structure format

    HTML embedded in Description (characters `<`, `>`, `&`) breaks the parser if not wrapped in CDATA or not escaped.

    Details, symptoms and fix →

    PunchOut Descriptions often contain formatted HTML (bullets, bold). Without CDATA wrapping or XML entity escaping, the cXML parser sees `<b>` as an XML tag and crashes.

    Symptoms

    • 406 Not Acceptable at parse
    • Buyer-side error mentioning 'unexpected element'

    Fix

    Either wrap HTML in `<![CDATA[...]]>` or escape characters: `&lt;`, `&gt;`, `&amp;`. Test with a product whose description contains HTML.

  • `deploymentMode="test"` left in prod

    environment

    The Request `deploymentMode` attribute tells the buyer whether it is test or prod. Forgotten at `test` in prod = routing to the buyer test env, silent failure.

    Details, symptoms and fix →

    During dev/QA, `deploymentMode="test"` is often hardcoded. At go-live, the switch to `production` is forgotten. The buyer routes to its test environment (different endpoints, different credentials) and never receives prod orders.

    Symptoms

    • Orders "sent successfully" on supplier side
    • Buyer receives no production orders
    • Everything worked in sandbox

    Fix

    Always set `deploymentMode` via env variable (`production` by default). Include in the release checklist.

Going further

Sources

This reference is sourced from the cXML Reference Guide v1.2.070, published by SAP Ariba on 16/05/2026, sections §3.1.9 (general Status codes), §3.1.10 (catalog upload codes) and §23.2.2 (digital signature codes).

The "Typical causes", "Debug checklist" and "Typical fix" sections are field observations from cXML integrations (recurring patterns observed across Ariba, Coupa, Oracle, Jaggaer, etc.), not part of the official spec. They are clearly labelled as such in the UI.