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.

Codes are returned at two different moments:

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.
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 and in the transaction resource.

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.
`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

422 Validation error
400 Compliance (payin)
401 Unauthorized
422 with code (account endpoints)

Returned by every endpoint when a field is invalid. Each field can carry more than one message.

{
  "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."]
  }
}

Returned by the payin endpoints when the payer document fails a compliance check. The data.code field carries the payin restriction code.

{
  "status": false,
  "message": "Compliance validation error",
  "data": {
    "code": "restriction_underage",
    "description": "Rejected due to document restriction underage Brazilian law"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key provided"
  }
}

Account and webhook configuration endpoints return a code per field.

{
  "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."
    }
  ]
}

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 and the description in rejection_description when you get the payout.

{
  "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.
`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

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.

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 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.

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.

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.

Payin status detail codes (webhook)

Returned in status_detail.code of the 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 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 and by 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 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 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.

Data Qualification statuses

Statuses returned by the Data Qualification 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

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.

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.

Never retry on the description

Implement rules on the code only. Descriptions are localized and may change without notice.

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.

Rejection reasons payout

Detailed guidance and scenarios for each payout code

Rejection reasons payin

Payin compliance codes with descriptions in English and Portuguese

Payout Status Flow

Lifecycle of a payout and its statuses

Webhooks

Signature, retries and payloads of the status notifications

Introduction

Account

Banks

Payin

Payout

Markup

Error Codes Reference

Error Codes Reference

HTTP status codes

Response formats

Payout status detail codes

Beneficiary and bank data

Pix

Compliance and antifraud

Balance and limits

Account restrictions

Duplicates and cancellations

Payin restriction codes (request time)

Payin status detail codes (webhook)

CPF Mismatch codes

QR Code decode errors

Account and webhook configuration codes

Data Qualification statuses

Handling errors in your integration

Rejection reasons payout

Rejection reasons payin

Payout Status Flow

Webhooks

​Error Codes Reference

​HTTP status codes

​Response formats

​Payout status detail codes

​Beneficiary and bank data

​Pix

​Compliance and antifraud

​Balance and limits

​Account restrictions

​Duplicates and cancellations

​Payin restriction codes (request time)

​Payin status detail codes (webhook)

​CPF Mismatch codes

​QR Code decode errors

​Account and webhook configuration codes

​Data Qualification statuses

​Handling errors in your integration

​Related Resources

Rejection reasons payout

Rejection reasons payin

Payout Status Flow

Webhooks

Error Codes Reference

HTTP status codes

Response formats

Payout status detail codes

Beneficiary and bank data

Pix

Compliance and antifraud

Balance and limits

Account restrictions

Duplicates and cancellations

Payin restriction codes (request time)

Payin status detail codes (webhook)

CPF Mismatch codes

QR Code decode errors

Account and webhook configuration codes

Data Qualification statuses

Handling errors in your integration

Related Resources