HTTP response codes

Use the HTTP code together with the response body to identify the result of a request.

2xx responses indicate success;
4xx responses indicate problems related to the request, authentication, authorization, resource or limits;
5xx responses indicate a processing failure on the Asaas side.

Most common codes

HTTP code	What it means	How to handle it
`200 OK`	The request was processed successfully.	Interpret the response body according to the endpoint used.
`204 No Content`	The request was processed successfully and has no response body.	Consider the operation completed according to the behavior documented for the endpoint.
`400 Bad Request`	Some required data is missing, invalid or does not comply with the operation rules.	Check the returned `errors` object to identify the field or rule that needs to be fixed.
`401 Unauthorized`	The request could not be authenticated. The key may be missing, invalid, inactive or belong to another environment.	Validate the `access_token` header and the key used. See Authentication.
`403 Forbidden`	The request was authenticated, but access was denied by an authorization or security rule.	Check the permissions, parameters used and security mechanisms configured for the account.
`403 Forbidden` on `GET` requests	The request may be sending content in the `body`.	Send `GET` calls with an empty body and use only the path params, query params and headers supported by the endpoint.
`403 Forbidden — Acesso negado. Code: XXXXXXXXX`	The request originated from an unauthorized IP.	Check the allowed addresses in the IP Whitelist. For subaccounts, validate the configuration applied by the parent account.
`404 Not Found`	The endpoint or resource provided was not found. This can also occur when the ID belongs to another account.	Confirm the URL, the ID provided and the account used for authentication.
`429 Too Many Requests`	An API limit was reached.	Identify in the response whether the block was caused by rate limit, quota or concurrency. See API Limits.
`500 Internal Server Error`	An internal failure occurred while Asaas was processing the request.	Log the request and response data. If the error persists, use this information to investigate the problem.

How to interpret the 429 error

429 Too Many Requests can occur in three situations.

Rate limit

Some endpoints have their own frequency limits.

Check the headers returned by the API:

RateLimit-Limit: 100
RateLimit-Remaining: 50
RateLimit-Reset: 30

When RateLimit-Remaining reaches 0, wait for the period indicated in RateLimit-Reset before sending new requests.

Quota limit

Each account can make up to 25,000 requests in a 12-hour period, regardless of the endpoint used.

The period starts with the first request and the counter is reset after 12 hours.

Concurrent request limit

The API allows up to 50 concurrent GET requests.

A request is considered concurrent when it is sent before a previous request has been answered.

If the limit is exceeded, the excess calls return 429 Too Many Requests.

For detailed diagnosis and handling, see Requests blocked due to lack of limit control.

📘
Response format
The API uses JSON in most requests and responses. Check the Content-Type documented for each endpoint, as some operations may return other formats, such as application/pdf.
GET requests must be sent without a body.

HTTP 400 response example

Validation errors may return more than one item in the errors array.

{
    "errors":[
        {
            "code":"invalid_value",
            "description":"O campo value deve ser informado"
        },
        {
            "code":"invalid_dueDate",
            "description":"A data de vencimento não pode ser inferior à hoje"
        }
    ]
}

Use code to identify the error programmatically and description to understand the cause returned by the API.

Most common codes

How to interpret the 429 error

Rate limit

Quota limit

Concurrent request limit

Response format

HTTP 400 response example

Next steps