Skip to main content
Every API error comes back in the same format, with a fixed code for your integration to handle and a text message for people to read.
string
required
Fixed identifier of the error. Use this code to decide what your integration does. The message text may change over time, so do not rely on it.
string
required
Description in Portuguese, meant to show up in logs and on support screens.
any
Extra information, when there is any, such as the list of invalid fields. Most errors do not include this field.
Treat any response outside the 2xx range as an error before reading data. When the call fails, data does not exist, and reading response.data.id throws a TypeError that hides the real cause.

Authentication and permission codes

When a 401 suddenly starts showing up, the most common cause is that the token has expired or your server’s outbound IP has changed. Check the token’s expiry date before investigating the network.

Request codes

An id from another company returns 404, exactly like an id that does not exist. This is on purpose: the API does not confirm that a record exists outside your account.

Business-rule codes

These codes show up when the request is correct, but the current state of the resource does not allow the operation.

How to handle each type of error

Each status range calls for a different reaction. A 400 comes back the same if you repeat the call without changing anything. A 429, on the other hand, should be repeated after the indicated wait, or the operation is lost.
Always record the error.code in your log, together with the method and path you called. With that information, support can locate the request, and it all fits on one line.