Interpreting API Errors

This page aims to present the "Request History", which allows the integrator to view all requests made by their application to the Gerencianet API. Thus, you will learn to interpret API returns and, of course, correct possible data validation errors or similar ones and identify consumptions/requests made by your application to our webservices.

Learning to use the "Request History" of the Gerencianet API

The API validates the data contained in the request that the integrated system sends to our webservices. In this way, depending on the endpoint your system is trying to consume, errors may be returned in certain situations. This also applies if you use a system or module que have integration with Gerencianet.

To access the "Request History", follow the steps:

• log in in your Gerencianet account;
• Access API > Minhas Aplicações > Sua Aplicação;
• Choose the environment used (production or development) and click on Histórico de Requisições (see where).

Check out the video where we teach you how to use the "Histórico de Requisições" of the API:

The following are some common examples of errors returned by the API due to some data not being in the correct format.

important

The following examples are also applicable if you are using a system or module that is already integrated with Gerencianet, after all, it is the API that is "behind" taking care of requests.

Example 1 - Create transaction/charge

When sending a POST to the route /v1/charge, the integrator will be creating a charge (or "transaction") with the status new,that is, the charge has been generated and is waiting for the payment method to be defined.

When creating a transaction, you can define, for example: item name, value, if it is a marketplace item, if it has shipping, inform a notification URL, etc.

For this example, let's try to create a charge whose total amount is less than R$ 5,00:

Now, after sending the code above, go through the "Histórico de Requisições" tab to check the response provided by the API:

As you can see in the image above, the response has code different from 200, that is, the consumption was not successful. In this case, the API requires the minimum amount of a charge to be R$ 5,00 - so in this case you must provide 500, without semicolons or semicolons (remembering that 500 is equivalent to R$ 5,00).

Example 2 - Link to payment method

When sending a POST to the /v1/charge/:id/pay route, where :id is the charge_id > of the desired transaction, the integrator will be associating the charge to a payment method.

At this point, you can define, for example: end customer data, address, expiration date (in case of a boleto), if there is a discount, if there is a fine/interest charge after the expiration date, etc.

For this example, we'll try to associate a charge with the payment method "boleto bancário" and with a due date in a format not supported by the API:

Now, after sending the code above, go through the "Histórico de Requisições" tab to check the response provided by the API:

As you can see in the image above, the response has code different from 200, that is, the consumption was not successful. In this case, the carnê must have a maximum of 12 (twelve) installments.

Exemplo 3 - Create carnet

When sending a POST to the route /v1/carnet, the integrator will be creating a carnet with the settings you defined.

At this time, you can define, for example: item name, value, quantity, customer data, address, number of installments, due date, etc.

For this example, let's try to create a 20 installment carnê:

Now, after sending the code above, go through the "Histórico de Requisições" tab to check the response provided by the API:

As you can see in the image above, the response has code different from 200, that is, the consumption was not successful. In this case, the carnê must have a maximum of 12 (twelve) installments.

Learning to search the error codes of the Gerencianet API

Seeking to facilitate the understanding of each error returned by our APIs, we provide a page that aims to present a list of all errors for consultation. To access it, click this link.

(+) HTTP status codes (2xx, 3xx, 4xx and 5xx)

Gerencianet uses HTTP responses to indicate success or failure in requests. Commonly, when we return responses with status 2xx it means that the request was successful; 3xx status indicates redirection; status 4xx indicates failures in sending data from the client; status 5xx indicates internal server errors.

If you want, check this link a table showing the HTTP codes of the most common responses, as well as their explanations and solutions.

(+) "Notification History" tab

This feature is available in the API of your Gerencianet account and allows you to view the POSTs that Gerencianet fires to the notification URL defined by the integrator. Saiba mais.