API Reference

Errors

Generation of QR codes

429 (Too Many Requests)

Indicates that the client sent an excessive number of requests in a short period of time, exceeding the limit established by the server. This error is often used to prevent abuse, such as denial of service (DoS) attacks, or to ensure API stability during times of high demand.

In the context of generating QR Codes, this error can only occur before the user makes the payment, when the same customer requests the creation of multiple QR Codes within a certain period of time. If the number of requests exceeds the limit, the API returns error 429.



{
  "status": 429,
  "message": "Too Many Requests"
}

Common Causes:

  • The client has exceeded the request limit allowed for a given time window (e.g. 100 requests per minute).
  • Lack of implementation of a rate-limiting system on the client that prevents excessive sending of requests.
  • Failures in error handling in the client code, resulting in continuous request loops.

Solution:

  • Implementation of Rate-Limiting on the Client: Configure your system to respect the request limits imposed by the API. The period of time that defines the request limit is parameterizable, that is, it can be adjusted according to the needs of each application. This allows the system to be flexible when dealing with different volumes of requests, preventing excessive use of resources without negatively impacting the user experience.
  • Review Request Standards: Ensure you are not making duplicate or unnecessary requests.

📘

Good Practice:

Always implement a handling mechanism for when error 429 is returned, ensuring that the application knows when to wait before resending the request, avoiding an overload of attempts.



Deposit

400 (Bad Request)

The error indicates that the server was unable to process the request due to a client error. This means that the request sent to the server is malformed, invalid, or cannot be understood. The error may be caused by a problem with the request syntax, incorrect parameters, or incomplete data.

HTTP 400 Bad Request
(Failed - Webhook will not be sent)

{
  "name": "DepositCreateError",
  "message": ["Error's reason"]
}

When the merchant does not exist

When a merchant (customer) does not exist in our database, the error below is displayed:

{
    "name": "DepositCreateError",
    "message": [
        "Erro desconhecido. Caso persista, contate o suporte."
    ]
}

When the TXID is invalid (greater than 35 characters)

When you pass a txID outside the accepted standard, you will receive the error:

{
    "name": "DepositCreateError",
    "message": [
        "Deposito Rejeitado. O ID da transação é maior que 35 caracteres."
    ]
}

The limit for generating QR Codes has been exceeded.

When the QR code generation limit is exceeded, you will receive the error below:

{
    "name": "DepositCreateError",
    "message": [
        "O limite para geração de QR Codes foi excedido."
    ]
}

Error in generating the QR Code by the financial institution

When we receive an error from the operating bank, you will see this error:

{
    "name": "DepositCreateError",
    "message": [
        "Erro desconhecido. Caso persista, contate o suporte."
    ]
}


Withdraw

Error 400 (Bad Request)

On a withdrawal attempt indicates that the request sent by the client was not processed correctly by the server. This can occur for several reasons related to incorrect formatting of the request, missing or invalid parameters.

HTTP 400 Bad Request
(Failed - Webhook will not be sent)

{
  "name": "WithdrawCreateError",
  "message": ["Error's reason"]
}


Duplicate transactionId failure

If you are selling a duplicate transaction Id, you will see this:

{
    "name": "WithdrawCreateError",
    "message": [
        "Identificador de transação já utilizado, favor utilizar outro."
    ]
}

Webhook

The "Webhook Failed" error indicates that the server was unable to deliver the webhook notification correctly. This problem can have several causes, related to both the client side (the application that consumes the webhook) and the server side (the API that sends the webhook).


Deposit

Webhook failed:
{
 "txid":"00000006",
 "value":0.01,
 "status":"failed",
 (Optional)"reason": "Deposit rejected because user does
not attend compliance rules."
}

Withdraw

Webhook failed:
{
 "txid":"00000015",
 "value":0.01,
 "status":"failed",
 (Optional)"reason": "Withdraw rejected because user does
not attend compliance rules."
}