Use o código HTTP junto ao corpo da resposta para identificar o resultado de uma requisição.
- respostas
2xxindicam sucesso; - respostas
4xxindicam problemas relacionados à requisição, autenticação, autorização, recurso ou limites; - respostas
5xxindicam falha no processamento pelo Asaas.
Códigos mais comuns
| Código HTTP | O que indica | Como tratar |
|---|---|---|
200 OK | A requisição foi processada com sucesso. | Interprete o corpo da resposta conforme o endpoint utilizado. |
204 No Content | A requisição foi processada com sucesso e não possui corpo de resposta. | Considere a operação concluída conforme o comportamento documentado no endpoint. |
400 Bad Request | Algum dado obrigatório está ausente, inválido ou não atende às regras da operação. | Consulte o objeto errors retornado para identificar o campo ou regra que precisa ser corrigido. |
401 Unauthorized | A requisição não pôde ser autenticada. A chave pode estar ausente, inválida, inativa ou pertencer a outro ambiente. | Valide o header access_token e a chave utilizada. Consulte Autenticação. |
403 Forbidden | A requisição foi autenticada, mas o acesso foi recusado por uma regra de autorização ou segurança. | Verifique permissões, parâmetros utilizados e mecanismos de segurança configurados para a conta. |
403 Forbidden em requisições GET | A requisição pode estar enviando conteúdo no body. | Envie chamadas GET com o body vazio e utilize apenas path params, query params e headers previstos pelo endpoint. |
403 Forbidden — Acesso negado. Code: XXXXXXXXX | A requisição foi originada de um IP não autorizado. | Confira os endereços permitidos na Whitelist de IPs. Em subcontas, valide a configuração aplicada pela conta responsável. |
404 Not Found | O endpoint ou recurso informado não foi encontrado. Também pode ocorrer quando o ID pertence a outra conta. | Confirme a URL, o ID informado e a conta utilizada na autenticação. |
429 Too Many Requests | Algum limite da API foi atingido. | Identifique na resposta se o bloqueio ocorreu por rate limit, cota ou concorrência. Consulte Limites da API. |
500 Internal Server Error | Ocorreu uma falha interna durante o processamento da requisição pelo Asaas. | Registre os dados da requisição e da resposta. Se o erro persistir, utilize essas informações na investigação do problema. |
Como interpretar o erro 429
O 429 Too Many Requests pode ocorrer em três situações.
Rate limit
Alguns endpoints possuem limites próprios de frequência.
Consulte os headers retornados pela API:
RateLimit-Limit: 100
RateLimit-Remaining: 50
RateLimit-Reset: 30Quando RateLimit-Remaining chegar a 0, aguarde o período indicado em RateLimit-Reset antes de enviar novas requisições.
Limite de cota
Cada conta pode realizar até 25.000 requisições em um período de 12 horas, independentemente do endpoint utilizado.
O período começa na primeira requisição e o contador é reiniciado após 12 horas.
Limite de requisições concorrentes
A API permite até 50 requisições GET concorrentes.
Uma requisição é considerada concorrente quando é enviada antes que uma requisição anterior tenha sido respondida.
Se o limite for ultrapassado, as chamadas excedentes retornam 429 Too Many Requests.
Para diagnóstico e tratamento detalhado, consulte Requisições bloqueadas por ausência de controle de limites.
Formato da respostaA API utiliza JSON na maioria das requisições e respostas. Consulte o
Content-Typedocumentado em cada endpoint, pois algumas operações podem retornar outros formatos, comoapplication/pdf.Requisições
GETdevem ser enviadas sembody.
Exemplo de resposta HTTP 400
Erros de validação podem retornar mais de um item no array errors.
{
"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"
}
]
}Utilize code para identificar programaticamente o erro e description para entender a causa retornada pela API.