Errors

HTTPS status code summaryCopied!

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 summaryCopied!

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 explanationCopied!

Error code	Error message	Remediation
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.
payout_cannot_be_cancelled	Payout cannot be cancelled. Status must be `awaiting_deposit`	Ensure the payout is in `awaiting_deposit` status before attempting confirmation.
payout_cannot_be_confirmed	Payout cannot be confirmed. Status must be `awaiting_deposit`.	Ensure the payout is in `awaiting_deposit` status before attempting confirmation.
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.