Errors
HTTPS status code summary
Below are the HTTP status codes you may encounter when making requests to our API, along with their meanings and recommended actions.
| Status code | Description |
|---|---|
| 200 - OK | The request was successful and the server returned the expected data. |
| 201 - Created | The request was successful and a new resource was created. |
| 400 - Bad Request | The request was invalid or cannot be served. The exact error is explained in the response payload. |
| 401 - Unauthorized | Authentication failed or user doesn't have permissions for requested operation. |
| 404 - Not Found | The requested resource could not be found. |
| 422 - Unprocessable Entity | The request was well-formed but was unable to be followed due to semantic errors. |
| 500 - Internal Server Error | Something went wrong on our servers. Please try again later. Our engineering team will be notified and work to fix the problem as soon as possible. |
Errors code summary
The following table summarizes the error responses and how to handle them in your API integration.
Each error object contains a code field that identifies the specific error type and a message field that provides a detailed explanation of what went wrong.
Here is an example of an error:
{
"error": {
"code": “unauthorized”,
"message": "Unauthorized access to the resource.",
}
}
Table of errors code and explanation
| Error code | Error message | Remediation |
|---|---|---|
| amount_out_of_range | Amount must be between 1 and 1000 BRL. | Make sure the amount you enter is within the allowed range. |
| webhook_config_already_exists | Webhook config already exists. | Check the existing webhook configuration using the GET /webhooks or update the existing webhook instead using the PUT /webhooks. |
| not_found | resource not found. |
Verify the resource ID and ensure it exists. |
| customer_mismatch | External account or wallet does not belong to the customer. |
Ensure the external_account belongs to the customer you are trying to complete the payout or create wallet. |
| payout_cannot_be_cancelled | Payout cannot be cancelled. Status must be awaiting_deposit. |
Ensure the payout is in awaiting_deposit status before attempting to cancel. |
| payin_cannot_be_cancelled | Pay-in cannot be cancelled. Status must be awaiting_deposit. |
Ensure the pay-in is in awaiting_deposit status before attempting to cancel. |
| payout_cannot_be_confirmed | Payout cannot be confirmed. Status must be awaiting_deposit. |
Ensure the payout is in awaiting_deposit status before attempting confirmation. |
| payin_cannot_be_confirmed | Pay-in cannot be confirmed. It’s only possible to confirm payouts. | |
| pix_key_invalid | The Pix key is invalid. | Check if the Pix key format is correct and verify that the Pix key exists in the Brazilian banking system. |
| quote_expired | Quote has been expired. | Request a new quote as quotes are only valid for 5 minutes. |
| quote_currency_mismatch | The quote currency does not match the requested payout currency. | Ensure the quote currency matches the payout currency or request a new payout with the correct currency. Alternatively, create a new quote and initiate a new payout. |
| internal_error | An unexpected error occurred. Please try again later. | Retry the request after a brief delay. If the error persists, contact support. |
| unauthorized | Unauthorized access to the resource. | Ensure your API key is correct and properly included in the Authorization header. |
| validation_error | Some fields are invalid. | Review the details field in the error object of the 400 response, which contains a list of validation errors with either missing_param or invalid_param error codes. |
| missing_param | param is required. |
Check the API documentation and include all required parameters. |
| invalid_param | param is invalid. |
Check the parameter format and value to ensure they match the specifications in the API documentation. |
