{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-heading","br","details","required","admonition"]},"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"},"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":["Understand Payout Drop-in error types, handle withdrawal failures, and recover safely."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payout Drop-in delivers most runtime failures through the required ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," callback. Configuration retrieval problems, empty method sets, card-on-file submit failures, and PayPal payout initiation failures route through this path."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Errors extend ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BaseSdkException"]}," and expose a stable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ErrorCode"]}," you can branch on, plus a human-readable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]},". Some payout initiation failures also populate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]}," with the merchant error payload from the payout API."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Not every failure uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Synchronous validation when calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayoutDropIn.initialize()"]}," throws immediately."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A rejected ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]}," promise causes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," to reject."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Some instrument lookups fail quietly by hiding a method instead of raising ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always wrap ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initialize()"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["try"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["catch"]},", and treat ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onSuccess"]}," as submission acknowledgement only. Confirm final payout state on your backend before updating the shopper's withdrawal status."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," runs during ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1700"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1701"]},"), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," usually settles without throwing. Rely on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," for those cases, and use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["try"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["catch"]}," for rejections such as a failed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-callback","__idx":2},"children":["Error callback"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All runtime SDK errors are delivered through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import {\n  PayoutDropIn,\n  type BaseSdkException,\n} from '@pxpio/web-components-sdk';\n\nconst payoutDropIn = PayoutDropIn.initialize({\n  // ... other config\n  onError: (error: BaseSdkException) => {\n    console.error('Payout Drop-in error:', {\n      errorCode: error.ErrorCode,\n      message: error.message,\n      name: error.name,\n      details: error.details,\n    });\n\n    showErrorMessage(mapToCustomerSafeMessage(error));\n  },\n});\n\ntry {\n  await payoutDropIn.create('payout-drop-in-container');\n} catch (error) {\n  console.error('Mount failed:', error);\n  showErrorMessage(\n    'We could not load withdrawal options. Please refresh or sign in again.'\n  );\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error-object-structure","__idx":3},"children":["Error object structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BaseSdkException"]}," exposes these fields:"]},{"$$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":"20%","data-label":"Property"},"children":["Property "]},{"$$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":["message"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A human-readable description of what went wrong."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ErrorCode"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Required","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The SDK error code in the form ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK####"]}," (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'SDK1700'"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'SDK1703'"]},"). Use this for programmatic handling."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The exception class name (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'PayoutDropInConfigNotFoundSdkException'"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'PayoutInitiationFailedException'"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]},{"$$mdtype":"Tag","name":"Break","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Details","attributes":{},"children":["unknown"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A structured payload on some payout initiation failures. Often the merchant error response, including fields such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorReason"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorCode"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlationId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["state"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stateData"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionId"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["systemTransactionId"]}," when the API returned them."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.ErrorCode"]}," for branching. There's no separate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," property on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BaseSdkException"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-categories","__idx":4},"children":["Error categories"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Errors fall into several groups based on when they occur and how you should respond."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configuration-and-mount-errors","__idx":5},"children":["Configuration and mount errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These occur while Drop-in loads site configuration or mounts into the container:"]},{"$$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":"Exception"},"children":["Exception"]},{"$$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":"Solution"},"children":["Solution"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayoutDropInConfigNotFoundSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1700"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Failed to retrieve Payout Drop-in configuration, or the configuration response was empty."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Confirm Payout Drop-in is enabled for the site, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["environment"]}," matches the session, and the configurations request succeeds in the network tab."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UnexpectedSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0000"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An unexpected failure during mount. For example, closed-loop allocation setup failing when closed-loop enforcement is active."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Log the full error, check Unity and network logs, and retry with a fresh session after addressing the underlying fault."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MissingConfigException"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MissingConfigEnvironmentException"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MissingConfigSessionException"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MissingConfigSessionIdException"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MissingConfigSessionHmackeyException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0100"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0104"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required initialisation fields are missing. These throw synchronously from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initialize()"]},". They don't call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fix the config object your backend supplies before calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initialize()"]}," again."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example maps mount-time configuration failures to shopper-safe messages:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"onError: (error: BaseSdkException) => {\n  if (error.ErrorCode === 'SDK1700') {\n    showErrorMessage(\n      'We could not load withdrawal settings. Please refresh the page or try again later.'\n    );\n    return;\n  }\n\n  if (error.ErrorCode === 'SDK0000') {\n    showErrorMessage(\n      'Something went wrong while loading withdrawals. Please try again.'\n    );\n    return;\n  }\n};\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"availability-errors","__idx":6},"children":["Availability errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Drop-in raises these when it mounts successfully but no withdrawal methods remain after session funding checks, instrument resolution, and blacklists:"]},{"$$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":"Exception"},"children":["Exception"]},{"$$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":"Solution"},"children":["Solution"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NoPayoutMethodsAvailableException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1701"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No payout methods are available for this session."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedFundingTypes"]},", the shopper ID from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]},", stored instruments, PayPal association status, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["methodConfig"]}," blacklists. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/drop-in/web/troubleshooting"},"children":["Troubleshooting"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1701"]}," commonly means one of the following:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The session allows methods, but the shopper has no eligible stored instruments."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Card-on-file methods were filtered out because no matching tokens remained."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["PayPal was allowed but no active linked account was found."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Blacklists removed every remaining instrument or payer."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a single method has no instruments, Drop-in usually hides that method. Drop-in raises ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1701"]}," when the filtered set becomes empty."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payout-submission-errors","__idx":7},"children":["Payout submission errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These errors occur while initiating a withdrawal for card, Apple Pay, Google Pay, or PayPal:"]},{"$$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":"Exception"},"children":["Exception"]},{"$$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":"User action"},"children":["User 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":["PayoutDropInCardPayoutFailedSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1703"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Card-on-file submit failed, or a closed-loop enforcement submit failed. Message is typically ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Card payout failed."]}," Closed-loop can use this exception even when more than one instrument was involved."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," and any ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]},". Offer retry or another method after checking backend state."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayoutInitiationFailedException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1703"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payout API returned a merchant error (card-on-file failed submit result, or PayPal panel error). Message is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Payout initiation failed: {reason}"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]},". Map provider reasons to shopper-safe copy, and correlate with your withdrawal record."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayoutCardOnFileBundleRequiredException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1702"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Card-on-file panel expected a token bundle that wasn't provided."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ensure ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," completed normally. If this appears in production, upgrade the SDK and contact support with logs."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both card payout failure and general payout initiation failure use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1703"]},". Closed-loop enforcement failures can also surface as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayoutDropInCardPayoutFailedSdkException"]}," with the same code. Don't branch business logic on the code alone. Distinguish by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]},", and always confirm transaction state on your backend before allowing another attempt."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayoutInitiationFailedException"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]}," is the merchant error object. The SDK builds ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," from, in order: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorReason"]},", then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stateData.message"]},", then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stateData.code"]},", then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorCode"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authentication-and-authorisation-errors","__idx":8},"children":["Authentication and authorisation errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Card-on-file submit wires authentication and authorisation evaluation callbacks. Payout intent skips the Unity 3D Secure authentication flow, so these codes are uncommon on the standard stored-instrument path. If they do appear, you may see the following:"]},{"$$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":"Exception"},"children":["Exception"]},{"$$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":"User action"},"children":["User 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":["CheckoutDropInAuthenticationFailedSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1114"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authentication failed, or authentication context was missing when authorisation was about to proceed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ask the shopper to try again, or choose another method."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CheckoutDropInAuthorisationFailedSdkException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1115"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authorisation evaluation didn't allow the payout to proceed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ask the shopper to try again later, or choose another method."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Prefer checking ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ErrorCode"]}," first, then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," for nuance. Treat these codes as uncommon on the standard payout stored-instrument path."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"validation-and-network-errors","__idx":9},"children":["Validation and network errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use these codes and message checks for validation and connectivity problems:"]},{"$$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":"Exception or detection"},"children":["Exception or detection"]},{"$$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":"User action"},"children":["User 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":["ValidationException"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0501"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Submit-path validation failure forwarded through card-on-file error handling."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Correct invalid input if your UI collects any, then retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Network error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Network failure reported by the SDK."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check connectivity and retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Message-based"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["None"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The message contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["session"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expired"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Recreate the payout session and refresh the page."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Message-based"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["None"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The message contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeout"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unavailable"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry shortly and show a retry control."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"failures-that-hide-a-method-instead-of-calling-onerror","__idx":10},"children":["Failures that hide a method instead of calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These don't always raise ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},":"]},{"$$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":"Scenario"},"children":["Scenario"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"SDK behaviour"},"children":["SDK behaviour"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What you should do"},"children":["What you should do"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Card token lookup fails or returns no usable tokens."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Card, Apple Pay, or Google Pay may be omitted from the accordion."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Confirm vault data for the shopper. Expect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1701"]}," only if every method is removed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PayPal account lookup fails, or is inactive or blacklisted."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PayPal is hidden and Drop-in continues with remaining methods."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check wallet association and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["methodConfig.paypal.blacklistedPayerId"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]}," is rejected."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," rejects. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," isn't used for that rejection."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Catch the rejection, re-authenticate, and call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," again."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"message-based-detection-for-sdk1703","__idx":11},"children":["Message-based detection for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1703"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Provider and payout API messages vary. After checking ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ErrorCode === 'SDK1703'"]},", inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," (and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]}," when present):"]},{"$$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":"Scenario"},"children":["Scenario"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Detection approach"},"children":["Detection approach"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"User guidance"},"children":["User guidance"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Declined"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The message contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["declined"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Try another method, or contact the card issuer or PayPal."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Insufficient funds"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The message contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["insufficient"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Choose another destination or reduce the amount if your product allows it."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Duplicate transaction"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The message or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details.stateData"]}," mentions a duplicate merchant transaction ID."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Don't resubmit the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionId"]},". Check backend status first."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Generic initiation failure"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The message starts with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Payout initiation failed:"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Show a safe generic withdrawal failure message and verify backend state."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example inspects ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1703"]}," messages for common decline patterns:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"onError: (error: BaseSdkException) => {\n  if (error.ErrorCode === 'SDK1703') {\n    const text = error.message.toLowerCase();\n\n    if (text.includes('declined')) {\n      showErrorMessage(\n        'This withdrawal was declined. Please try another method or contact your provider.'\n      );\n      return;\n    }\n\n    if (text.includes('insufficient')) {\n      showErrorMessage(\n        'There are insufficient funds on the selected destination. Please choose another method.'\n      );\n      return;\n    }\n\n    showErrorMessage(\n      \"Your withdrawal could not be completed. Please try again or contact support.\"\n    );\n    return;\n  }\n};\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling-patterns","__idx":12},"children":["Error handling patterns"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"basic-handling","__idx":13},"children":["Basic handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Log for support, show a safe shopper message, and clear loading state:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import type { BaseSdkException } from '@pxpio/web-components-sdk';\n\nonError: (error: BaseSdkException) => {\n  console.error('Payout error:', {\n    errorCode: error.ErrorCode,\n    message: error.message,\n    name: error.name,\n  });\n\n  hideLoadingOverlay();\n\n  if (error.ErrorCode === 'SDK1701') {\n    showErrorMessage('No withdrawal methods are available right now.');\n    return;\n  }\n\n  if (error.ErrorCode === 'SDK1700') {\n    showErrorMessage(\n      \"We couldn't load withdrawal settings. Please refresh or try again later.\"\n    );\n    return;\n  }\n\n  showErrorMessage(\n    \"Your withdrawal could not be completed. Please try again or contact support.\"\n  );\n};\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"handling-with-recovery","__idx":14},"children":["Handling with recovery"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add monitoring, limited retries for transient faults, and alternative-method prompts for submission declines:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"let retryCount = 0;\nconst MAX_RETRIES = 3;\n\nonError: (error: BaseSdkException) => {\n  logErrorToMonitoring({\n    category: 'payout_error',\n    errorCode: error.ErrorCode,\n    message: error.message,\n    exception: error.name,\n    merchantTransactionId: currentWithdrawalId,\n    sessionId: sessionData.sessionId,\n  });\n\n  analytics.track('payout_failed', {\n    errorCode: error.ErrorCode,\n    retryCount,\n  });\n\n  hideLoadingOverlay();\n\n  const isRetryable =\n    error.ErrorCode === 'SDK0500' ||\n    error.message.toLowerCase().includes('timeout') ||\n    error.message.toLowerCase().includes('unavailable');\n\n  if (isRetryable && retryCount < MAX_RETRIES) {\n    retryCount += 1;\n    showWarningMessage(\n      `Connection issue (attempt ${retryCount}/${MAX_RETRIES}). Please try again.`\n    );\n    showRetryButton();\n    return;\n  }\n\n  retryCount = 0;\n\n  if (error.ErrorCode === 'SDK1701') {\n    showErrorMessage('No withdrawal methods are available right now.');\n    return;\n  }\n\n  if (error.ErrorCode === 'SDK1114' || error.ErrorCode === 'SDK1115') {\n    showErrorMessage(\n      \"We couldn't authenticate this withdrawal. Please try again or use a different method.\"\n    );\n    return;\n  }\n\n  if (error.ErrorCode === 'SDK1703') {\n    showErrorMessage(\n      \"Your withdrawal could not be completed. Please try again or choose another method.\"\n    );\n    offerAlternativeMethods();\n    return;\n  }\n\n  if (\n    error.message.toLowerCase().includes('session') ||\n    error.message.toLowerCase().includes('expired')\n  ) {\n    showErrorMessage('Your session has expired. Please refresh the page.');\n    showRefreshButton();\n    return;\n  }\n\n  showErrorMessage(\n    \"Your withdrawal could not be completed. Please try again or contact support.\"\n  );\n};\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Never mark a withdrawal as paid because the shopper retried after an error. Confirm status with your webhook handler or a server-side transaction lookup first. A failed client callback doesn't prove that no payout was created."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"logging-checklist","__idx":15},"children":["Logging checklist"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Log the following for support engineers:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ErrorCode"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionId"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sessionId"]}," (never log ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hmacKey"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Useful fields from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["details"]}," such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["correlationId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["systemTransactionId"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stateData"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Don't log inbound API tokens, encryption keys, wallet JWTs, or full card tokens in client logs."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"recovery-summary","__idx":16},"children":["Recovery summary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Map each common code to a recovery action:"]},{"$$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"},"children":["Error"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Recovery"},"children":["Recovery"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1700"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fix site and environment configuration. Recreate the session, then retry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1701"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Explain that no methods are available. Prompt linking a card or PayPal, or contact support."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1703"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allow retry only after backend shows no successful transaction for that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantTransactionId"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1114"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK1115"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Uncommon on the standard payout path. If they appear, offer retry or another method. Don't assume the payout was created."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0500"]}," or timeout"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Show retry with a small attempt limit."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Mount or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onGetShopper"]}," failure"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Re-authenticate the shopper. Recreate the payout session, then call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create()"]}," again."]}]}]}]}]}]},"headings":[{"value":"Error handling","id":"error-handling","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Error callback","id":"error-callback","depth":2},{"value":"Error object structure","id":"error-object-structure","depth":3},{"value":"Error categories","id":"error-categories","depth":2},{"value":"Configuration and mount errors","id":"configuration-and-mount-errors","depth":3},{"value":"Availability errors","id":"availability-errors","depth":3},{"value":"Payout submission errors","id":"payout-submission-errors","depth":3},{"value":"Authentication and authorisation errors","id":"authentication-and-authorisation-errors","depth":3},{"value":"Validation and network errors","id":"validation-and-network-errors","depth":3},{"value":"Failures that hide a method instead of calling onError","id":"failures-that-hide-a-method-instead-of-calling-onerror","depth":3},{"value":"Message-based detection for SDK1703","id":"message-based-detection-for-sdk1703","depth":2},{"value":"Error handling patterns","id":"error-handling-patterns","depth":2},{"value":"Basic handling","id":"basic-handling","depth":3},{"value":"Handling with recovery","id":"handling-with-recovery","depth":3},{"value":"Logging checklist","id":"logging-checklist","depth":3},{"value":"Recovery summary","id":"recovery-summary","depth":2}],"frontmatter":{"seo":{"title":"Error handling"}},"lastModified":"2026-11-12T15:20:37.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/payout/drop-in/web/error-handling","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}