Error Catalog

These are the public PUNCHOUT_* response codes returned by the PunchOut module. A security response may also include more specific codes in its errors array.

Availability and setup

Code	Meaning and next check
`PUNCHOUT_DISABLED`	PunchOut is disabled in the resolved store scope.
`PUNCHOUT_MISSING_REQUIRED_FIELDS`	OCI buyer/hook values or required cXML setup values were not parsed.
`PUNCHOUT_BUYER_MISSING`	The request did not contain the buyer identity required for context creation.
`PUNCHOUT_BUYER_NOT_ALLOWED`	No active buyer matched protocol, identity and store scope.
`PUNCHOUT_AUTHENTICATION_FAILED`	Protocol or optional transport credentials did not match; read the returned messages.
`PUNCHOUT_INVALID_CUSTOMER_REFERENCE`	A supplied/assigned customer reference is invalid for the resolved context.
`PUNCHOUT_INTERNAL_ERROR`	An unexpected server error occurred; use the correlation time and Magento logs without exposing the request secret.

Request security

PUNCHOUT_SECURITY_VALIDATION_FAILED is the top-level error. Its nested codes can include:

Nested code	Meaning and next check
`PUNCHOUT_IP_NOT_ALLOWED`	Magento's resolved client IP is outside the configured list.
`PUNCHOUT_SIGNATURE_SECRET_MISSING`	Strict mode is on but the scoped signature secret is empty.
`PUNCHOUT_SIGNATURE_MISSING`	No signature header/parameter was supplied.
`PUNCHOUT_SIGNATURE_INVALID`	The supplied digest is not a 64-character hexadecimal SHA-256 value.
`PUNCHOUT_SIGNATURE_MISMATCH`	HMAC secret or signed payload representation differs.

Return URL

The setup controller returns PUNCHOUT_INVALID_HOOK_URL with one or more details:

Nested code	Meaning and next check
`PUNCHOUT_MISSING_HOOK_URL`	No OCI hook or cXML form-post URL was found.
`PUNCHOUT_INSECURE_HOOK_URL`	The URL is not HTTPS.
`PUNCHOUT_HOOK_URL_BLOCKED_HOST`	`localhost` was used outside sandbox mode.
`PUNCHOUT_HOOK_URL_BLOCKED_IP`	A literal or resolved address is private/reserved outside sandbox mode.
`PUNCHOUT_HOOK_URL_DNS_RESOLVE_FAILED`	The hostname produced no usable A/AAAA address.

Context and cart

Code	Meaning and next check
`PUNCHOUT_MISSING_TOKEN`	No token was supplied in the supported parameter/header.
`PUNCHOUT_CONTEXT_NOT_FOUND`	Logout could not resolve the supplied token.
`PUNCHOUT_CONTEXT_EXPIRED`	The token is absent, expired or already logged out for the requested action.
`PUNCHOUT_CART_ADD_FAILED`	SKU, quantity, availability or Magento add-to-cart validation failed.
`PUNCHOUT_CART_UPDATE_FAILED`	No item was resolved or an update value was invalid.
`PUNCHOUT_CART_REMOVE_FAILED`	No matching item identifier was supplied/found.
`PUNCHOUT_CART_GET_FAILED`	Magento could not resolve or read the bound quote.
`PUNCHOUT_OPERATION_RESTRICTED`	The active storefront operation policy does not permit this action.

OCI product functions

Code	Meaning and next check
`PUNCHOUT_OCI_VERSION_INVALID`	The request contains an unsupported OCI version.
`PUNCHOUT_OCI_VERSION_MISMATCH`	The request version differs from the OCI version configured on the buyer profile.
`PUNCHOUT_OCI_PROFILE_VERSION_INVALID`	The buyer profile has no supported OCI version. Open the profile and save a valid value.
`PUNCHOUT_OCI_FUNCTION_NOT_SUPPORTED`	The requested OCI function is not implemented for this flow.
`PUNCHOUT_OCI_DETAIL_PRODUCT_REQUIRED`	`DETAIL` or `DETAILADD` was sent without `PRODUCTID`.
`PUNCHOUT_OCI_DETAIL_PRODUCT_NOT_FOUND`	The configured SKU or external product identifier did not resolve to an eligible product.
`PUNCHOUT_OCI_DETAILADD_VERSION_NOT_SUPPORTED`	`DETAILADD` was requested for a buyer profile that does not use OCI 5.

Transfer and mapping

Code	Meaning and next check
`PUNCHOUT_VALIDATION_ERROR`	Read the returned `errors` list for item, URL, mapping or currency details.
`PUNCHOUT_EMPTY_ITEMS`	The transfer has no cart lines.
`PUNCHOUT_ITEM_<n>_MISSING_DESCRIPTION`	The numbered line has no description.
`PUNCHOUT_ITEM_<n>_INVALID_QTY`	The numbered line has a non-positive quantity.
`PUNCHOUT_ITEM_<n>_MISSING_UNIT`	The numbered line has no unit.
`PUNCHOUT_ITEM_<n>_MISSING_PRICE`	The numbered line has a missing, non-numeric or negative price.
`PUNCHOUT_MIXED_ITEM_CURRENCIES`	cXML lines do not share one currency.
`PUNCHOUT_MAPPING_INVALID_PROFILE`	The context mapping is absent or not a usable runtime profile.
`PUNCHOUT_MAPPING_INVALID_RULE_CONFIGURATION`	A saved rule cannot be executed safely.
`PUNCHOUT_MAPPING_REQUIRED_<TARGET>`	A mandatory mapped target is empty after formatting/fallback.
`PUNCHOUT_MAPPING_INVALID_NEW_ITEM_UNIT`	An OCI unit contains more than three characters.
`PUNCHOUT_MAPPING_INVALID_NEW_ITEM_LEADTIME`	OCI lead time is not an integer with at most five digits.
`PUNCHOUT_MAPPING_INVALID_NEW_ITEM_MANUFACTCODE`	The OCI manufacturer code exceeds ten characters.
`PUNCHOUT_UNSUPPORTED_PROTOCOL`	The transfer resolved neither OCI nor cXML.

Request replay

Code	Meaning and next check
`PUNCHOUT_REQUEST_REPLAY_IN_PROGRESS`	Another call with this operation and `X-Punchout-Request-Key` is still processing.
`PUNCHOUT_REQUEST_REPLAY_CONFLICT`	The operation and key were reused with a different request hash in the same Store view.
`PUNCHOUT_REQUEST_KEY_REQUIRED`	A manual retry of an unknown delivery was requested without `X-Punchout-Request-Key`.

A successful exact retry returns the previously stored response and is not an error.

Inbound OrderRequest processing

Code	Meaning and next check
`PUNCHOUT_INVALID_ORDER_REQUEST`	The cXML document is malformed or does not contain a supported OrderRequest.
`PUNCHOUT_PO_NUMBER_MISSING`	No PO/order number was parsed.
`PUNCHOUT_PO_EMPTY_ITEMS`	The PO contains no parsed line items.
`PUNCHOUT_PO_CANCEL_FAILED`	A legacy context-cart cancellation could not clear the linked PunchOut quote.
`PUNCHOUT_INVALID_PRICE`	A submitted or authoritative unit price is invalid for processing.
`PUNCHOUT_ITEM_MISSING`	Magento cannot resolve a submitted product using the configured product reference.
`PUNCHOUT_ORDER_REJECTED`	An inbound policy or Magento quote validation rejected the order.
`PUNCHOUT_MANUAL_REVIEW`	The request requires an administrator to review and process or reject it.
`PUNCHOUT_PRICE_REVIEW`	A price difference reached the configured manual-review action.
`PUNCHOUT_QUANTITY_REVIEW`	A changed returned-cart quantity requires review.
`PUNCHOUT_NEW_ITEM_REVIEW`	A product not present in the returned cart requires review.
`PUNCHOUT_REMOVED_ITEM_REVIEW`	The approved order removed a returned-cart line that requires review.
`PUNCHOUT_SNAPSHOT_REVIEW`	The returned-cart snapshot is missing or expired and the configured action is manual review.
`PUNCHOUT_UPDATE_REVIEW`	An OrderRequest update requires manual review.
`PUNCHOUT_CANCELLATION_REVIEW`	An OrderRequest delete requires manual review.
`PUNCHOUT_MANUALLY_REJECTED`	An administrator rejected the inbound order.
`PUNCHOUT_PROCESSING_ERROR`	Quote or order processing raised an unexpected error. Inspect the detail record and Magento log for the same time.
`PUNCHOUT_ORDER_PROCESSING`	The same OrderRequest is still being processed. Retry the unchanged request later.
`PUNCHOUT_RETRY_EXHAUSTED`	The configured inbound-order processing attempts have been used. Review the stored failure before retrying manually.

ASN and invoice documents

Code	Meaning and next check
`PUNCHOUT_ASN_ENDPOINT_MISSING`	No effective ASN URL is configured for shipment delivery.
`PUNCHOUT_INVOICE_ENDPOINT_MISSING`	No effective Invoice URL is configured for invoice delivery.
`PUNCHOUT_ASN_PAYLOAD_MISSING`	Magento could not build or load the retained shipment payload.
`PUNCHOUT_INVOICE_PAYLOAD_MISSING`	Magento could not build or load the retained invoice payload.
`PUNCHOUT_ASN_SHIPMENT_ID_MISSING`	No shipment/ASN/notice number was supplied.
`PUNCHOUT_ASN_EMPTY_ITEMS`	No shippable line items were supplied or parsed.
`PUNCHOUT_ASN_DATA_INCOMPLETE`	Magento could not hydrate the required shipment, order or supplier cXML data.
`PUNCHOUT_ASN_DELIVERY_FAILED`	The HTTPS POST raised an error or returned non-2xx.
`PUNCHOUT_INVOICE_NUMBER_MISSING`	No invoice number was supplied or parsed.
`PUNCHOUT_INVOICE_TOTAL_INVALID`	Invoice total is missing or not greater than zero.
`PUNCHOUT_INVOICE_CURRENCY_MISSING`	No currency was supplied or parsed.
`PUNCHOUT_INVOICE_DATA_INCOMPLETE`	Magento could not hydrate the required invoice, order or supplier cXML data.
`PUNCHOUT_INVOICE_DELIVERY_FAILED`	The HTTPS POST raised an error or returned non-2xx.
`PUNCHOUT_DOCUMENT_TYPE_UNSUPPORTED`	A queue record refers to an unsupported outbound document type.
`PUNCHOUT_DOCUMENT_CONFIGURATION_ERROR`	Required routing or supplier configuration is incomplete.
`PUNCHOUT_DOCUMENT_PAYLOAD_MISSING`	Document generation completed without an outbound payload.
`PUNCHOUT_DOCUMENT_PAYLOAD_DECRYPTION_FAILED`	Magento cannot decrypt the retained outbound payload. Check the installation's encryption key and deployment history.
`PUNCHOUT_INBOUND_ORDER_REFERENCE_MISSING`	A queue row has no durable inbound-order reference.
`PUNCHOUT_DOCUMENT_STORE_MISMATCH`	The queue row and its inbound order belong to different Store Views.
`PUNCHOUT_QUEUE_OWNERSHIP_LOST`	The worker lost its queue lease before it could save the outbound payload. The row was not completed by that worker.
`PUNCHOUT_DELIVERY_OUTCOME_UNKNOWN`	Magento cannot tell whether the remote system accepted the document. Check the receiver before using the dedicated manual retry action.
`PUNCHOUT_QUEUE_PROCESSING_ERROR`	A queue handler raised an unexpected processing exception.

When the API message and trace do not explain a failure, reproduce it in the simulator with privacy-safe values and then inspect Magento logs for the same time window.