{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-heading","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":["Handle payout component errors in the iOS SDK."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payout components on iOS report errors through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BaseSdkException"]},", which exposes an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorCode"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDKXXXX"]},") and an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorMessage"]},". Configuration and wallet validation failures are thrown when you call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pxpCheckout.create"]},". Runtime failures during SDK-initiated payout execution are delivered through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," on the payout submission component."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," into the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayoutSubmissionComponentConfig"]}," initialiser, the parameter type is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Error"]},". Cast it to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BaseSdkException"]}," to read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorCode"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorMessage"]},". If you assign ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["config.onError"]}," after initialisation, the stored property already receives a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BaseSdkException"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For field-level rules and examples, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payout/components/ios/paypal/data-validation"},"children":["Data validation"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-errors-are-raised","__idx":2},"children":["When errors are raised"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following table summarises where payout errors appear."]},{"$$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":"Stage"},"children":["Stage"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"How you receive the error"},"children":["How you receive the error"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Component creation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Thrown from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pxpCheckout.create"]},". For example, a missing email or payer ID, invalid amount, or invalid currency."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["SDK-initiated payout execution"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delivered to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]}," on the payout submission component (typically as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayoutFailedException"]},")."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["proceedPayoutWithSdk"]}," set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},", only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onClick"]}," runs. Use that callback to notify your backend so it can execute the payout. Create-time validation still throws from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-codes","__idx":3},"children":["Error codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following tables list payout-related codes from the iOS SDK."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"common-and-sdk-configuration","__idx":4},"children":["Common and SDK configuration"]},{"$$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":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0000"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unexpected error."]}]},{"$$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":["Not implemented."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0100"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing SDK config."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0101"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing SDK config: environment."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0102"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing SDK config: session data."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0103"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing SDK config: session ID."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0104"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing SDK config: session HMAC key."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0106"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Intent type does not support the requested component."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0200"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Component name must not be empty."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0202"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Component configuration is required for the component type."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Network error."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0501"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Validation error."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"paypal-payout-validation","__idx":5},"children":["PayPal payout validation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These codes are thrown when you create the amount, receiver, or submission component."]},{"$$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":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0803"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PayPal payout receiver is required (email or payer ID is missing, or the email is empty)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0805"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Receiver type must be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Email"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0807"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Receiver type must be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Email"]}," when the wallet is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Paypal"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0808"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid email format for the receiver."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0809"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PayPal payer ID is required (empty string after trim)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0810"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Amount must be a valid number (not NaN or infinite)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0811"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Amount must be a positive number greater than 0."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0813"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Currency code must be a non-empty string."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0814"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Currency code must be a 3-letter ISO 4217 currency code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0815"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid currency code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0816"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Email exceeds the maximum length of 127 characters."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0817"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PayPal payer ID exceeds the maximum length of 13 characters."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0818"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PayPal payer ID contains invalid characters. Only alphanumeric characters (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["A-Z"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["a-z"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0-9"]},") are allowed."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0804"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0806"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SDK0812"]}," are defined in the SDK but are not thrown by the current payout amount, receiver, or submission create paths. Prefer the codes in the table above when mapping customer-facing messages."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payout-execution-failures","__idx":6},"children":["Payout execution failures"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When an SDK-initiated payout fails at runtime, the submission component typically delivers a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PayoutFailedException"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},". Its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorCode"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorMessage"]}," are the code and reason returned by the API (or a related transport code such as an HTTP status code), not a fixed payout validation code."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example","__idx":7},"children":["Example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example catches create-time errors and handles runtime failures in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["onError"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"do {\n    let config = PayoutSubmissionComponentConfig(\n        submitText: \"Withdraw with\",\n        onPrePayoutSubmit: {\n            return PrePayoutSubmitResult(isApproved: true)\n        },\n        onError: { error in\n            guard let error = error as? BaseSdkException else { return }\n            print(\"Payout error: \\(error.errorCode) - \\(error.errorMessage)\")\n            showErrorDialog(error.errorMessage)\n        }\n    )\n    let component = try pxpCheckout.create(.payoutSubmission, componentConfig: config)\n} catch let error as BaseSdkException {\n    print(\"Create failed: \\(error.errorCode) - \\(error.errorMessage)\")\n    showErrorDialog(error.errorMessage)\n} catch {\n    print(\"Create failed: \\(error.localizedDescription)\")\n}\n","lang":"swift"},"children":[]}]},"headings":[{"value":"Error handling","id":"error-handling","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"When errors are raised","id":"when-errors-are-raised","depth":2},{"value":"Error codes","id":"error-codes","depth":2},{"value":"Common and SDK configuration","id":"common-and-sdk-configuration","depth":3},{"value":"PayPal payout validation","id":"paypal-payout-validation","depth":3},{"value":"Payout execution failures","id":"payout-execution-failures","depth":3},{"value":"Example","id":"example","depth":2}],"frontmatter":{"seo":{"title":"Error handling"}},"lastModified":"2026-11-11T13:23:40.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/payout/components/ios/paypal/error-handling","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}