Tema
Erros
Regra geral
Use o status HTTP para saber o resultado:
200ou201: deu certo;204: deu certo, sem corpo (apagar cliente);- qualquer outro: não deu certo.
O campo success não basta
Nem toda resposta tem success, e algumas respostas de erro vêm com "success": true (por exemplo, recusa do banco ao criar cobrança e 404 de cliente). Decida sempre pelo status HTTP.
As mensagens vêm em português, no campo message.
Códigos
| Status | Quando | Formato do corpo |
|---|---|---|
401 | Token ausente, vencido ou inválido. | { "message": "Acesso negado." } |
401 | Credenciais erradas em POST /access/account/get-token. | Envelope com message. Veja Autenticação. |
403 | O usuário de API não tem a permissão exigida. | { "code": 403, "success": false, "message": "..." } |
404 | O recurso não existe ou é de outra conta. | Envelope com message. |
409 | Repetição de uma cobrança ainda em andamento ou em verificação. | Envelope. Veja Idempotência. |
422 | Dados inválidos. | Validação. |
4xx / 5xx | O banco recusou a emissão do Pix ou do boleto. | Envelope com a mensagem do banco. |
500 | Erro inesperado. | Envelope ou { "message": "Server Error" }. |
Limite de chamadas (429)
Informação ainda não publicada — fale com o suporte.
Envelope
A maioria das respostas usa este formato:
json
{
"code": 404,
"success": false,
"data": null,
"message": "Cobrança não encontrada"
}| Campo | O que é |
|---|---|
code | O status HTTP. Pode não vir. |
success | Indicação de sucesso. Veja o aviso acima. |
data | O resultado, os erros por campo ou null. |
message | Mensagem para leitura humana. |
Validação (422)
Há dois formatos. O seu sistema deve aceitar os dois.
Formato 1 — campos inválidos na entrada (o mais comum):
json
{
"message": "O campo data de vencimento é obrigatório. (e mais 1 erro)",
"errors": {
"due_date": ["O campo data de vencimento é obrigatório."],
"payment_method": ["O campo payment method é obrigatório."]
}
}Formato 2 — regra conferida durante a operação (ex.: valor bloqueado ao alterar uma cobrança, recusa do banco ao mudar o vencimento):
json
{
"message": "Dados de entrada inválidos.",
"success": false,
"data": {
"amount": ["Não é possível alterar o valor de uma cobrança com Pix ou boleto já emitido. Para cobrar outro valor, cancele esta cobrança e crie uma nova."]
}
}Nos dois, cada campo tem uma lista de mensagens. Leia errors e, se não existir, data.
js
function validationErrors(body) {
return body.errors ?? (body.data && typeof body.data === 'object' ? body.data : {});
}O texto exato das mensagens pode mudar. Use o nome do campo na sua lógica, não o texto.
O que fazer em cada caso
| Status | Ação recomendada |
|---|---|
401 | Peça um novo token e repita a chamada uma vez. Se voltar 401, confira as credenciais. |
403 | Peça a quem administra a conta para revisar as permissões do usuário de API. |
404 | Confira o id ou code. Não repita. |
409 | Espere e consulte a lista de cobranças antes de tentar de novo. |
422 | Corrija os campos indicados. Não repita igual. |
5xx ou falha de rede | Em criação de cobrança, repita com a mesma Idempotency-Key. Veja Idempotência. |
Problema que continua? Abra um chamado no portal: Como abrir um chamado. Informe o método, o caminho, o status HTTP, a data e hora e o id da cobrança. Nunca mande o token nem a chave da conta no chamado.