Erros e Códigos de Status

A API retorna um envelope JSON consistente. O campo statusCode no corpo acompanha o status HTTP.

Envelope de sucesso

{
  "data": { "...": "..." },
  "msg": "SUCCESS",
  "statusCode": 200
}

msg pode ser uma string ("SUCCESS", "success", "OK") ou uma lista (["OK"]), conforme o endpoint.

Envelope de erro

{
  "data": null,
  "msg": ["Mensagem de erro"],
  "statusCode": 401
}

Códigos de status usados

Código	Uso
200	Sucesso
201	Recurso criado (ex.: cadastro de blacklist)
400	Erro de negócio / provedor (ex.: boleto inválido, falha na consulta)
401	Erro de validação de campos ou credenciais inválidas
402	Token ausente/inválido/expirado, ou credenciais PIX não configuradas
404	Registro não encontrado, ou exportação enfileirada (relatórios assíncronos)
500	Erro interno do servidor

:::note Exportações assíncronas Endpoints de exportação (/payments/export, /transactions/export, etc.) retornam 404 com a mensagem "Aguarde, seu arquivo está sendo gerado..." — isso indica que o relatório foi enfileirado, não que houve erro. :::

Variações por domínio

Alguns endpoints PIX retornam um envelope próprio:

{
  "nsu": null,
  "documento": null,
  "msg": "Chave pix não cadastrada...",
  "statusCode": 402
}

ou, em validação de campo:

{ "error": "Campo document é obrigatório" }