> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wepayout.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes Reference

> Consolidated reference of HTTP status codes, rejection codes and status detail codes returned by the WEpayments API and webhooks

# Error Codes Reference

This page consolidates every error and rejection code the WEpayments API can return, in one place. Each code is machine-readable and stable: use the **code** in your integration logic and treat the description as informational only, since the text may change.

<Note>
  Codes are returned at two different moments:

  1. **When the request is sent** — the API answers with an HTTP error and nothing is created. You can fix the request and send it again.
  2. **After the transaction is created** — the API answers `201` and the transaction is later canceled or rejected during processing. The reason is delivered in the `status_detail` object of the [webhook](/concepts/webhooks) and in the transaction resource.
</Note>

## HTTP status codes

All endpoints use standard HTTP status codes. The table below applies to every product (payout, payin, account, data qualification).

| HTTP status | Meaning | What to do |
| - | - | - |
| `200` / `201` | Request accepted. For payouts and charges, `201` means the transaction was created and will be processed asynchronously. | Track the final status by webhook or by querying the transaction. |
| `400` | The request could not be processed: for example, a compliance restriction on a payin, the same `invoice` sent again while the previous request is still being processed, invalid bank account data, or an invalid or expired QR Code. | Check the `message` (and `data.code` for payin) and correct the request. |
| `401` | The API key is missing, invalid or expired. | Check the `Authorization: Bearer` header. See [Authentication](/authentication). |
| `403` / `404` | The resource (merchant, payment, charge, End-to-End ID) was not found, is disabled or is not available to your user. | Check the identifier and the account the API key belongs to. |
| `409` | A conflicting operation is already running (for example, a bulk webhook resend job). | Wait for the running job to finish. |
| `422` | One or more fields failed validation. The response lists every invalid field in `errors`. | Fix the fields listed and send the request again. |
| `451` | The beneficiary account is not one of the accounts authorized for your account (only when this restriction is enabled). | Use an authorized beneficiary account or contact support. |
| `503` | The service is temporarily unavailable for scheduled maintenance. | Retry after the time informed in the `Retry-After` header. |
| `500` | Unexpected error. | Retry later. If the error persists, contact support with the request details. |

### Response formats

<Tabs>
  <Tab title="422 Validation error">
    Returned by every endpoint when a field is invalid. Each field can carry more than one message.

    ```json theme={null}
    {
      "message": "The given data was invalid.",
      "errors": {
        "beneficiary.document.number": ["The document provided is not a valid CPF."],
        "pix.pix_key": ["Pix key type not identified. Review the pix_key value."]
      }
    }
    ```
  </Tab>

  <Tab title="400 Compliance (payin)">
    Returned by the payin endpoints when the payer document fails a compliance check. The `data.code` field carries the [payin restriction code](#payin-restriction-codes-request-time).

    ```json theme={null}
    {
      "status": false,
      "message": "Compliance validation error",
      "data": {
        "code": "restriction_underage",
        "description": "Rejected due to document restriction underage Brazilian law"
      }
    }
    ```
  </Tab>

  <Tab title="401 Unauthorized">
    ```json theme={null}
    {
      "error": {
        "code": "unauthorized",
        "message": "Invalid API key provided"
      }
    }
    ```
  </Tab>

  <Tab title="422 with code (account endpoints)">
    Account and webhook configuration endpoints return a `code` per field.

    ```json theme={null}
    {
      "message": "The given data was invalid.",
      "errors": [
        {
          "field": "event",
          "code": "webhook_already_exists",
          "params": [],
          "message": "A webhook for this event already exists for this account."
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## Payout status detail codes

Returned after a payout is created, when it ends as **Canceled** (`6`) or **Rejected** (`4`). The code is delivered in `status_detail.code` of the [payout webhook](/cash-out/payout-webhook) and the description in `rejection_description` when you [get the payout](/api-reference/cash-out/payout/get-unique-payment).

```json theme={null}
{
  "id": 123456,
  "invoice": "INV-0001",
  "status": { "id": 6, "name": "Canceled" },
  "updated_at": "2026-09-30 10:15:00",
  "status_detail": { "code": "47", "detail": "Insufficient Balance" }
}
```

The **Retry** column tells you whether a new payout for the same beneficiary makes sense:

* **After fix** — send a new payout after correcting the data indicated.
* **Later** — the condition is temporary; send a new payout later.
* **No** — compliance or policy decision; a new payout will be canceled again.

### Beneficiary and bank data

| Code | Reason | Retry | What to do |
| - | - | - | - |
| `1` | Rejected by bank | After fix | The beneficiary bank rejected the payment. Check the beneficiary data. |
| `2` | Invalid document or bank data | After fix | Check the beneficiary CPF/CNPJ and bank account data. |
| `3` | Blocked account | After fix | The beneficiary account is blocked. Ask the beneficiary for another account. |
| `4` | Divergent beneficiary | After fix | The account or Pix key does not belong to the informed document. See [CPF Mismatch](/features/cpf-mismatch). |
| `5` | Wrong bank account or branch | After fix | Check the branch and account number. |
| `6` | Wrong bank code | After fix | Check the bank code or ISPB. |
| `7` | Wrong bank branch | After fix | Check the branch number. |
| `8` | Wrong bank account | After fix | Check the account number and digit. |
| `9` | Wrong name | After fix | Check the beneficiary name. |
| `10` | Wrong bank details | After fix | Check the beneficiary bank data. |
| `15` | Irregular CPF | No | The beneficiary CPF is irregular with the Federal Revenue. |
| `20` | Divergence in CPF/CNPJ information | After fix | The informed CPF/CNPJ does not match the account holder. |
| `22` | Account closed | After fix | The beneficiary account is closed. Ask the beneficiary for another account. |
| `29` | Beneficiary's bank does not allow payment type indicated | After fix | Use another payment method or account. |
| `30` | Account does not allow payment type indicated | After fix | The account does not accept this payment type (for example, salary accounts). |
| `31` | Incorrect account type | After fix | Check the account type (checking, savings, payment or salary). |
| `32` | Pix rejected by beneficiary bank | After fix | Check the beneficiary data or ask for another account. |

### Pix

| Code | Reason | Retry | What to do |
| - | - | - | - |
| `17` | Invalid pix key | After fix | The Pix key does not exist or is invalid. Check the key with the beneficiary. |
| `26` | Beneficiary's bank does not allow payment type indicated | After fix | The beneficiary bank does not support this Pix operation. |
| `27` | DICT Quota Exceeded | Later | The Pix key query limit was reached. |
| `46` | Token Bucket request limit exceeded | Later | The Pix key query limit was reached. |
| `48` | Pix key entry blocked | After fix | The Pix key is blocked. Ask the beneficiary for another key. |
| `53` | Failed to send to bank | Later | The payment could not be sent to the bank. |

### Compliance and antifraud

| Code | Reason | Retry |
| - | - | - |
| `28` | Canceled by Compliance | No |
| `33` | Canceled by Compliance. Tax number on OFAC list | No |
| `34` | Canceled by Compliance. Tax number on INTERPOL list | No |
| `35` | Canceled by Compliance. Tax number on UN list | No |
| `36` | Canceled by Compliance. Tax number on European Union list | No |
| `37` | Canceled by Compliance. Tax number is disabled (deceased) | No |
| `38` | Canceled by Compliance. Tax number is PEP (politically exposed person) | No |
| `39` | Canceled by Compliance. Tax number blocked on RFB (Brazilian Federal Revenue) | No |
| `40` | Canceled due to CPF restriction: underage (Brazilian law) | No |
| `41` | Canceled due to age restriction (over 80 years old) as per compliance policy | No |
| `43` | Restricted by KYC | No |
| `51` | Payment rejected after preventative review | No |
| `52` | The recipient's document is irregular with the Federal Revenue Service or appears on international restrictive lists | No |
| `54` | The payer's document is irregular with the Federal Revenue Service or appears on international restrictive lists | No |

<Note>
  When a compliance check needs manual review, the payout is not canceled: it goes to **In Review** (`5`) until the review is finished. See [Payout Status Flow](/cash-out/status-flow).
</Note>

### Balance and limits

| Code | Reason | Retry | What to do |
| - | - | - | - |
| `14` | The payment amount is above the allowed for the account type | After fix | Reduce the amount or use another beneficiary account. |
| `18` | Value exceed the max amount | After fix | The amount is above the maximum allowed. Reduce the amount. |
| `47` | Insufficient Balance | Later | Check your balance with [Get Balance](/api-reference/account/get-balance) before sending the payout again. |
| `49` | Transactional limit exceeded | After fix | Split into smaller payments or contact support to review your limits. |

### Account restrictions

| Code | Reason | Retry | What to do |
| - | - | - | - |
| `WE0001` | The payment was made to an unregistered account | After fix | The beneficiary account is not one of the accounts authorized for your account. |
| `WE0002` | The payment was made to an unauthorized institution | After fix | The beneficiary institution is not authorized for your account. |

### Duplicates and cancellations

| Code | Reason | Retry | What to do |
| - | - | - | - |
| `11` | Canceled due to duplicated invoice | No | Another payout with the same `invoice` already exists. Query it by `invoice` instead of sending a new one. |
| `13` | Client request payment cancelation | No | Canceled at your request or by a restriction configured for your account (for example, a blocked beneficiary). |
| `16` | Cancelation requested by client | No | Canceled at your request. |
| `42` | Canceled due to external error | Later | The receiving institution or payment network could not complete the payment. Check the beneficiary data and send the payout again, or contact support. |

<Tip>
  A payout returned by the beneficiary after it was paid is not a rejection: it keeps the **Paid** status and receives a refund substatus. See [About Payments](/cash-out/about-payments).
</Tip>

## Payin restriction codes (request time)

Returned with HTTP `400` and `message: "Compliance validation error"` when the payer document fails a compliance check at charge creation. The code is in `data.code`.

| Code | Description |
| - | - |
| `restriction_overdue` | Rejected due to document restriction |
| `restriction_underage` | Rejected due to document restriction: underage (Brazilian law) |
| `restriction_deceased_holder` | Rejected due to document restriction: deceased holder |
| `restriction_canceled` | Rejected due to document restriction: canceled document |
| `restriction_unknown` | Rejected due to document restriction: unknown document |
| `restriction_pending_regularization` | Rejected due to document restriction: pending regularization |
| `restriction_suspended` | Rejected due to document restriction: suspended document |
| `restriction_partners_and_ownership` | Rejected due to document restriction: partners and ownership |
| `restriction_judicial_block` | Rejected due to document restriction: judicial block |
| `restriction_cpf_irregular` | Rejected due to document restriction: irregular CPF |
| `restriction_list_restrict` | Rejected due to document restriction: restrictive list |
| `restriction_pep` | Rejected due to document restriction: PEP (Politically Exposed Person) |
| `restriction_age_above_limit` | Rejected due to age restriction as per compliance policy |
| `restriction_ofac` | Rejected due to document restriction on OFAC list |
| `restriction_interpol` | Rejected due to document restriction on INTERPOL list |
| `restriction_onu` | Rejected due to document restriction on UN list |
| `restriction_euro` | Rejected due to document restriction on European Union list |

Descriptions in Portuguese and handling guidance are available in [Rejection reasons payin](/cash-in/rejection-reasons).

## Payin status detail codes (webhook)

Returned in `status_detail.code` of the [payin webhook](/cash-in/payin-webhook) when a Pix charge ends as **Rejected**. These codes are only sent when the "Account Mismatch" functionality is enabled for the merchant.

| Code | Description |
| - | - |
| `reason_payer_divergence` | CPF mismatch: the payer is not the account holder |
| `reason_payer_restriction_deceased_holder` | CPF restriction: deceased holder |
| `reason_payer_restriction_canceled` | CPF restriction: canceled document |
| `reason_payer_restriction_suspended` | CPF restriction: suspended document |
| `reason_payer_pending_regularization` | CPF restriction: pending regularization |
| `reason_payer_restriction_unknown` | CPF restriction: unknown document |
| `gl_cpf_payer_restriction_underage` | CPF restriction: underage (Brazilian law) |
| `reason_payer_restriction_age_above_limit` | Restriction: age above limit (over 80 years) |
| `pending_challenge` | Pending challenge |
| `reason_payer_restriction_receita` | CPF restriction (Tax Authority) |
| `payer_restriction_high_risk` | CPF high risk |
| `pending_review_manual` | Payment created; awaiting manual review |
| `payer_restriction` | Rejected per compliance policy |
| `reason_payer_restriction_pep` | PEP (Politically Exposed Person) |
| `reason_payer_restriction_list_restrict` | CPF on restrictive list |
| `reason_payer_restriction_cpf_irregular` | Irregular CPF |
| `reason_payer_restriction_judicial_block` | Judicial block |
| `reason_payer_restriction_partners_and_ownership` | Certified restriction (partners/ownership) |
| `reason_payer_restriction_ofac` | CPF on OFAC list |
| `reason_payer_restriction_interpol` | CPF on INTERPOL list |
| `reason_payer_restriction_onu` | CPF on UN list |
| `reason_payer_restriction_euro` | CPF on European Union restrictive list |
| `reason_payer_restriction_pld` | KYC restriction |
| `WE0001` | The payment was made from an unregistered account |
| `WE0002` | The payment was made from an unauthorized institution |

## CPF Mismatch codes

Returned by the [CPF Mismatch](/features/cpf-mismatch) feature when the document of the person paying or receiving does not match the account holder.

| Code | Flow | Description |
| - | - | - |
| `RESTRICTION_PAYER_DIVERGENCE` | Payin | The payer's CPF does not match the account holder's CPF |
| `BENEFICIARY_DIVERGENT` | Payout | The beneficiary's CPF does not match the registered holder's CPF (delivered as payout code `4`) |

## QR Code decode errors

Returned by [Decode QR Code](/api-reference/cash-out/payout/decode-qr-code) and by [Create Payment](/api-reference/cash-out/payout/create-payment) with `payment_method: QRCODE`.

| HTTP status | Message | Meaning |
| - | - | - |
| `400` | QR Code is invalid or expired | The EMV string could not be decoded or the charge has expired. |
| `400` | QR Code doesn't have a valid status | Dynamic QR Codes are accepted only while the charge is active. |
| `400` | (amount validation) | The QR Code amount is fixed (`is_amount_changeable: false`) and a different `amount` was sent. |
| `404` | End to End ID not found | The `end_to_end_id` expired (5 minutes after decode) or was already used. Decode the QR Code again. |

## Account and webhook configuration codes

Returned with HTTP `422` by the [webhook setup](/api-reference/account/webhook/webhook-setup) and related endpoints, in the `code` field of each error.

| Code | Description | What to do |
| - | - | - |
| `webhook_already_exists` | A webhook for this event already exists for this account. | Use [Update](/api-reference/account/webhook/webhook-update) instead of registering again. |
| `invalid_account` | The account does not exist or is not linked to your merchant. | Check the `account_id` sent. |
| `unauthorized` | Invalid API key provided (HTTP `401`). | Check the API key. See [Authentication](/authentication). |

## Data Qualification statuses

Statuses returned by the [Data Qualification](/api-reference/data-qualification/get-status) service, used to validate bank account data before sending payouts.

| Status | Name | Description |
| - | - | - |
| `1` | Received | Request received and stored in our database |
| `9` | Awaiting | Awaiting balance to be processed |
| `999` | Processing | Validation sent for processing |
| `5` | Valid data | The account data is valid |
| `6` | Invalid data | The validation payment was rejected by the bank |
| `7` | Validation not possible on this step | The account data provided cannot be validated |

## Handling errors in your integration

<Steps>
  <Step title="Request refused (HTTP 4xx/5xx)">
    Nothing was created. For `422`, read every field in `errors`; for `400` on payin, read `data.code`; for `503`, honor `Retry-After`. Fix and resend.
  </Step>

  <Step title="Transaction canceled or rejected after creation">
    Read `status_detail.code` from the webhook or the transaction resource. Use the tables above to decide whether to correct data and send a new transaction, wait, or stop.
  </Step>

  <Step title="Never retry on the description">
    Implement rules on the **code** only. Descriptions are localized and may change without notice.
  </Step>

  <Step title="Use a new invoice for retries">
    When a payout ends as Canceled, Failed or Rejected, a new `invoice` is required for the retry. The only exception is **Invalid Data** (`11`), which may be resubmitted with the same `invoice` after correcting the data.
  </Step>
</Steps>

## Related Resources

<CardGroup cols={2}>
  <Card title="Rejection reasons payout" icon="circle-xmark" href="/cash-out/rejection-reasons">
    Detailed guidance and scenarios for each payout code
  </Card>

  <Card title="Rejection reasons payin" icon="circle-xmark" href="/cash-in/rejection-reasons">
    Payin compliance codes with descriptions in English and Portuguese
  </Card>

  <Card title="Payout Status Flow" icon="diagram-project" href="/cash-out/status-flow">
    Lifecycle of a payout and its statuses
  </Card>

  <Card title="Webhooks" icon="webhook" href="/concepts/webhooks">
    Signature, retries and payloads of the status notifications
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.