/explain-error

description: Explain a PayPal API error code or message and provide actionable solutions
argument-hint: <error_code or error_message>
allowed-tools: Read, Grep

If "$ARGUMENTS" is empty, respond only with: "Please provide a PayPal error code or message. Example: `/paypal:explain-error INSTRUMENT_DECLINED`" and stop.

If "$ARGUMENTS" does not match any known PayPal error code or message pattern, respond with: "Unknown error code or message: `$ARGUMENTS`. This may be a typo, a third-party error, or a new PayPal error not yet in this reference. Check https://developer.paypal.com/api/rest/reference/orders/v2/errors/ (Orders v2), https://developer.paypal.com/api/rest/responses/ (HTTP status codes), or the Errors section of the relevant API reference (Vault: https://developer.paypal.com/api/payment-tokens/v3, Payouts: https://developer.paypal.com/api/payments.payouts-batch/v1, Webhooks: https://developer.paypal.com/api/webhooks/v1) for the full list." Then do your best to explain what the error string suggests based on its name, and stop — do not fabricate retry behavior or related errors.

Otherwise, explain the PayPal error "$ARGUMENTS". Provide:

1. **What it means** — plain-language explanation 2. **Common causes** — most likely reasons this occurs 3. **How to fix it** — specific, actionable steps 4. **Code example** — detect the user's programming language by scanning any open files with Read/Grep; default to Node.js if no language is found. Show proper error handling including how to catch the error, display a user-friendly message, and whether to retry. 5. **Related errors** — only list errors from the Key error reference below that are meaningfully related (same HTTP status, same flow, or must be handled together). Do not suggest errors outside this list.

Key error reference:

**General (any API):**

• `INVALID_REQUEST` (400) — malformed body or missing fields; inspect the `details[]` array for the specific `field` and `issue`
• `UNAUTHORIZED` (401) — expired or missing access token; refresh via `POST /v1/oauth2/token`
• `AUTHENTICATION_FAILURE` (401) — missing `Authorization` header or invalid credentials; an expired bearer token usually comes back as `invalid_token` — mint a new token via `POST /v1/oauth2/token`
• `NOT_AUTHORIZED` (403) — valid token but the app lacks the scope or feature for this operation (`details[].issue` is usually `PERMISSION_DENIED`); on `GET /v1/reporting/balances` or `/v1/reporting/transactions` it means **Transaction Search** is not enabled for the app — enable it in the Developer Dashboard (Apps & Credentials → your app → Features) and mint a new token
• `PERMISSION_DENIED` (403) — account not eligible for this API; check Developer Dashboard feature eligibility
• `RESOURCE_NOT_FOUND` (404) — resource ID does not exist or belongs to a different account
• `INVALID_RESOURCE_ID` (404) — the `issue` behind most 404s (Orders, Payments, Payouts, Webhooks, Transaction Search): the ID is mistyped, belongs to another account, or was created in the other environment (sandbox vs. live)
• `DUPLICATE_TRANSACTION` (409) — idempotency key already succeeded; retrieve the existing resource instead
• `PREVIOUS_REQUEST_IN_PROGRESS` (409 `RESOURCE_CONFLICT`) — a request with the same `PayPal-Request-Id` is still being processed; wait, then retry with the **same** ID — do not generate a new one
• `RATE_LIMIT_REACHED` (429) — back off with exponential retry; honor the `Retry-After` header
• `INTERNAL_SERVER_ERROR` (500) — retry with the same `PayPal-Request-Id` idempotency key; log `debug_id`

**Orders v2:**

• `INSTRUMENT_DECLINED` (422) — buyer's payment method declined; ask for a different payment method, do not retry the same instrument
• `TRANSACTION_REFUSED` (422) — risk engine decline; do not retry automatically
• `ORDER_NOT_APPROVED` (422) — the buyer has not approved the order yet; send them to the `rel: approve` link (or wait for the JS SDK `onApprove` callback) before calling capture or authorize
• `ORDER_ALREADY_CAPTURED` / `ORDER_ALREADY_AUTHORIZED` (422) — only one capture (`intent=CAPTURE`) or one authorization (`intent=AUTHORIZE`) is allowed per order; `GET /v2/checkout/orders/{id}` to recover the existing capture or authorization ID instead of retrying
• `ORDER_ALREADY_COMPLETED` (422) — a completed order cannot be patched; create a new order instead
• `PAYER_ACTION_REQUIRED` (422) — the buyer must complete a step (3D Secure, bank or APM approval) before the order can be captured; redirect them to the `rel: payer-action` HATEOAS link, then retry
• `AMOUNT_MISMATCH` (422) — `amount.value` must equal `item_total + tax_total + shipping + handling + insurance - shipping_discount - discount` from `amount.breakdown`
• `PAYPAL_REQUEST_ID_REQUIRED` (400) — creating an order with a `payment_source` requires a `PayPal-Request-Id` header

**Vault (Payment Method Tokens v3) and saved payment methods:**

• `NOT_ENABLED_TO_VAULT_PAYMENT_SOURCE` (403 on `/v3/vault/*`, 422 on Orders) — the API caller or merchant is not allowed to vault this payment source; enable **Vault** for the app in the Developer Dashboard or contact PayPal support — not retryable
• `VAULT_INSTRUCTION_REQUIRED` (422) — `payment_source.*.attributes.vault` was sent without an instruction; add `store_in_vault: "ON_SUCCESS"`
• `INVALID_VAULT_ID` (422) — `vault_id` is invalid or not found: wrong environment, deleted token, or a setup token used where a payment token is required
• `MISMATCHED_VAULT_ID_TO_PAYMENT_SOURCE` (422) — the token does not match the `payment_source` key it was sent under (e.g. a PayPal token inside `payment_source.card`)
• `PAYER_ACTION_REQUIRED` (422, Vault v3) — the setup token has not been approved by the payer; complete the approval flow before `POST /v3/vault/payment-tokens`
• `SETUP_TOKEN_ALREADY_TOKENIZED` (422) — the setup token was already exchanged for a payment token; reuse that payment token
• `TOKEN_NOT_FOUND` (404) — the token ID does not exist (deleted, other accou