{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-heading","img"]},"type":"markdown"},"seo":{"title":"Error handling","description":"Transform your commerce with PXP's unified platform—seamless payments, real-time insights, and global growth in one powerful integration.","lang":"en-UK","siteUrl":"https://developer.pxp.io","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"error-handling","__idx":0},"children":["Error handling"]},{"$$mdtype":"Tag","name":"SubHeading","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reference for error messages returned by Tap+ and their descriptions."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sdk-errors","__idx":1},"children":["SDK errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Proper error handling is essential, as it ensures that your application can gracefully manage unexpected situations, provide meaningful feedback to users, and maintain system stability while protecting sensitive data."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When an SDK error occurs, you'll receive an error code (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDKXXXX"]},") and descriptive error message."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following table describes all the possible SDK errors codes."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error code"},"children":["Error code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Suggested action"},"children":["Suggested action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0001"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An unknown error has occurred."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Log the error and contact support if recurring."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0002"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Network connectivity issue occurred."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check your internet connection and retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0003"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Network operation attempted on the main thread."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ensure network operations run off the main thread."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0004"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request sent successfully from SDK to POS, but read/write data timed out."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check the transaction status. Log the event for tracking and reach out to support if this occurs frequently. The auto-reversal should be handled by POS."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0005"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Failed to connect."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify the server address and network, then attempt to reconnect."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0006"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Illegal arguments."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Please check the arguments."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0007"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid parameters."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Please check the parameters."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"on-device-errors","__idx":2},"children":["On-device errors"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"50%","data-label":"Error message"},"children":["Error message "]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Display"},"children":["Display"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Init PHOS SDK Failed! Device ID: 1fd3ea386c1956f5"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/tap-plus-init-error.51dfc3afb8822d2cced2439208c55bb4e7caa69648c798f3240a1e574ffcd705.544b2584.png","alt":"","withLightbox":true,"width":"","height":""},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["This error appears when developer mode is turned on or a TCP connection failure occurs."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"errorCode\": \"InvalidRequest\", \"errorReason\": \"Site identifier does not match the authorised value in configuration. Merchant identifier does not match the authorised value in configuration. Entry type must be 'Instore' for POS transactions Point of interaction is required.\" }"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The site ID or merchant ID is incorrect."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Error during connection and listening - {specific error message}\" - Environment Variable PHOS_INIT_STATUS set to \"FAIL\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A PHOS initialisation failure occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Serial number could not be found. Please re-enter the serial number and try again."]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/tap-plus-activation-error.b5a0b251c544978648696473391e9f9839a17b411d10bb59e37d10e788869924.544b2584.png","alt":"","withLightbox":true,"width":"","height":""},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An HMAC activation error occurred (HMAC activation not Found)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Please enter the serial number below into the Unity Portal to complete the activation process."]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The activation process is in progress. To complete it, enter the device's serial number in the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://portal.pxp.io","target":"_blank"},"children":["Unity Portal"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"errorCode\": \"AuthorizationRequestFailed\", \"errorReason\": \"Invalid or missing HMAC signature\" }"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The HMAC signature is invalid or missing."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Polling Status Error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A polling status error occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Transaction declined"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A transaction failure occurred (void amount)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"errorCode\": \"InvalidRequest\", \"errorReason\": \"Merchant identifier does not match the authorised value in configuration.\" }"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An invalid merchant ID was provided."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"errorCode\": \"InvalidRequest\", \"errorReason\": \"Funding type must be 'Card'\" }"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An invalid funding type was provided."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"errorCode\": \"InvalidRequest\", \"errorReason\": \"Entry type must be 'Instore' or 'Moto' for POS transactions\" }"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An invalid entry type was provided."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"errorCode\": \"InvalidRequest\", \"errorReason\": \"Point of Sale ID does not match the authorised value in configuration\" }"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An invalid point-of-sale ID was provided."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Invalid currency codes for POS '{pointOfSaleID}'. Default Currency Code must be exactly 3 uppercase letters and not be null"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An invalid currency code was provided. It should be in ISO 4217 format. For example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USD"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Funding type not found in request"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The funding type is missing from your request."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Transaction amount should be greater than 0 for {entryType} transactions / Transaction amount is invalid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The transaction amount provided is invalid."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fundingdata.card.cardScheme has an invalid value"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card scheme provided is invalid."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Communication error when connecting to auth provider service '{authProvider}'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A communication error occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Error when connecting to auth provider service '{authProvider}'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An error occurred when connecting."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["General execution error when connecting to acquirer '{acquirer}'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A general execution error occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Timeout when connecting to auth provider service '{authProvider}'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A timeout occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Transaction method not found in request"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The transaction method provided is invalid."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["No auth provider has been set for merchant '{merchant}'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An authorisation error occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Error when getting auth provider information for merchant '{merchant}'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A routing error occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Error when connecting to BIN lookup service for card '{card}'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A BIN lookup error occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["A general execution error when connecting to BIN lookup service for card '{card}'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A BIN lookup error occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Card '{card}' not found"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A BIN lookup error occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Error when connecting to card routing service for merchant '{merchant}'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A card routing error occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Timeout when connecting to card routing service for merchant '{merchant}'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A card routing error occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Communication error when connecting to card routing service for merchant '{merchant}'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A card routing error occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["General execution error when connecting to card routing service for merchant '{merchant}'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A card routing error occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["A card routing error occurred."]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A card routing error occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["General execution error when connecting to point of sale service for site '{site}' and point of sale '{merchantPointOfSaleID}'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A point-of-sale service error occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Communication error when connecting to point of sale service for site '{site}' and point of sale '{merchantPointOfSaleID}'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A point-of-sale service error occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Error when connecting to point of sale service for site '{site}' and point of sale '{merchantPointOfSaleID}'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A point-of-sale service error occurred."]}]}]}]}]}]},"headings":[{"value":"Error handling","id":"error-handling","depth":1},{"value":"SDK errors","id":"sdk-errors","depth":2},{"value":"On-device errors","id":"on-device-errors","depth":2}],"frontmatter":{"seo":{"title":"Error handling"}},"lastModified":"2026-02-04T16:09:30.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/tap-plus/sdk/error-handling","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}