Error Codes
The following tables summarize the error messages returned by the Pix Payments API. They can help you troubleshoot issues in pay-in or payout transactions.
The tables are organized considering the three endpoints Bitso currently has to handle Pix transactions. Recall that withdrawals are two-step transactions:
- Generate Dynamic QR Code (Pay-in)
- Withdrawal Preview (Payout)
- Withdrawal Confirm (Payout)
Generate Dynamic QR Code (Pay-in)
| Error Code | Error Message | Remediation |
|---|---|---|
| 0402 | The amount exceeds the maximum limit for this transaction. Please try again with a lower amount. | Your Bitso account manages user and transaction monthly limits, so the transferred amount must lie within those limits. You can consult these figures directly on the Profile > Limits section of your Bitso web or mobile application. Contact our Support Desk at [email protected] if you need help increasing your testing account's limits. For limit modification on a production account, reach out to your account manager. |
| 0404 | The receiver PIX key is not valid; you need to create one before using it. | The receiver's Pix key you submitted in the pix_key parameter is invalid. |
| 0410 | The tax_id related to the payer is not allowed to perform this operation. | The sender's taxpayer ID you submitted in the tax_id parameter failed the screening. |
| 0343 | The amount must be greater than 0. | The amount submitted must be a positive number. |
| 0303 | Invalid field: [amount, payer.name, payer.taxId, pix_key]. | The parameters amount, payer, and pix_key are all required. |
Withdrawal Preview (Payout)
Before the service can create a withdrawal, users must preview the transaction's data and provide a confirmation. In the request body of the preview call, you must include the taxonomy parameters and the beneficiary's data. The preview call returns the transaction's end-to-end ID.
| Error Code | Error Message | Remediation |
|---|---|---|
| 500 | Internal server error | You must provide the taxonomy object and all of its fields. |
Withdrawal Confirm (Payout)
To confirm the data returned by the preview call, you must send a confirmation call, including the provided end-to-end ID. This call creates the withdrawal.
| Error Code | Error Message | Remediation |
|---|---|---|
| 0101 | We couldn't send this amount. Please try again or contact our Customer Support team. | The sender's or receiver's limits verification failed. The amount transferred must lie within authorized limits. Recall that your Bitso account manages user and transaction monthly limits, so the transferred amount must lie within those limits. You can consult these figures directly on the Profile > Limits section of your Bitso web or mobile application. Contact our Support Desk at [email protected] if you need help increasing your testing account's limits. For limit modification on a production account, reach out to your account manager. |
| 0111 | We couldn't process your sending request. Try again in a few minutes. | Verify that the end-to-end ID you are sending is valid. |
| 0702 | The recipient account must be under your name. | The recipient account holder must match the sending account holder. |
| 0303 | The field amount is missing. | The amount parameter is required in the request body. |
| 0304 | We are not able to send with this method. Try again in a few minutes. | The method specified in the taxonomy parameters is temporarily unavailable. |
Updated about 1 year ago