O que você vai receber
Uma resposta
application/problem+json é um objeto problem details do RFC 9457. A referência da sua API traz uma página Tratamento de erros que nomeia o formato que aquela API responde.
type– Uma referência URI que identifica o tipo do erro.title– Um resumo curto do tipo de problema.status– O código de status HTTP.detail– Orientação específica dessa ocorrência.errors– Lista opcional de detalhe por campo, cada item com umlocatione umamessage.instance– Referência URI opcional para essa ocorrência específica.
Códigos de erro
O formato do código varia por API. Você vai encontrar um
<PREFIX>-<NNNN> com prefixo, um número puro, um
token em minúsculas e um código que a contraparte de um trilho atribuiu. O core do Midaz usa números puros como 0002
e 0009.
A referência da sua API traz uma página Tratamento de erros que nomeia o formato que aquela API usa e lista
os códigos que ela emite.
Códigos de status HTTP
Estes são os códigos de status que você vai encontrar com mais frequência. Uma API pode responder outros, e a própria página Tratamento de erros dela os lista.
Orientação de nova tentativa
Você não deve tentar de novo todo erro. A tabela a seguir ajuda você a decidir:
Estratégia de backoff exponencial
Para erros repetíveis, use backoff exponencial para evitar sobrecarregar o serviço:- Primeira tentativa: aguarde 1 segundo
- Segunda tentativa: aguarde 2 segundos
- Terceira tentativa: aguarde 4 segundos
- Máximo de tentativas: pare depois de 3–5 tentativas
- Jitter: adicione um pequeno atraso aleatório (0–500ms) a cada espera para evitar thundering herd
Solução de problemas por categoria
Campos ausentes ou inválidos (400)
Uma resposta400 pode carregar detalhe por campo que nomeia os campos com problema.
Causas comuns:
- Campo obrigatório omitido do corpo da requisição
- Valor do campo não corresponde ao tipo esperado (por exemplo, string em vez de UUID)
- Valor do campo excede o tamanho máximo
- Campos extras inesperados no corpo da requisição
- Leia o detalhe por campo na resposta de erro
- Compare sua requisição com a referência da API para esse endpoint
Autenticação e autorização (401/403)
Causas comuns:- Credencial ausente
- Token expirado ou revogado
- O token não concede acesso ao endpoint solicitado
- Verifique se a requisição traz a credencial que sua API espera
- Solicite um novo token se o atual expirou
- Verifique se quem chama tem as permissões exigidas
Recurso não encontrado (404)
Causas comuns:- ID de recurso incorreto no caminho da URL
- Recurso removido de forma lógica (soft delete)
- Recurso pertence a uma organização ou ledger diferente
- Verifique o ID do recurso no caminho da URL
- Liste os recursos para confirmar que o ID existe
Erros de conflito (409)
Causas comuns:- Criar um recurso com um nome que já existe (por exemplo, nome de ledger duplicado, nome de regra duplicado)
- Tentar uma operação que já está completa (por exemplo, transação duplicada)
- Leia a mensagem de erro para identificar qual campo causou o conflito
- Use um valor diferente (por exemplo, renomeie) ou recupere o recurso existente
- Para operações idempotentes, verifique se o recurso existente corresponde à sua intenção
Limitação de taxa (429)
Causas comuns:- Muitas requisições em um período curto
- Implemente backoff exponencial com jitter
- Reduza a frequência das chamadas de API
- Agrupe operações em lote quando possível
Erros de servidor e timeout (500/502/503/504)
Causas comuns:- Interrupção temporária do serviço
- Alta carga na plataforma
- Dependência upstream indisponível
- Tente de novo as leituras com backoff exponencial (1s, 2s, 4s). Concilie os comandos antes de tentar de novo, porque o resultado original pode ser desconhecido.
- Se o erro persistir depois de 3–5 novas tentativas, contate o suporte
- Registre uma resposta de erro com dados sensíveis removidos para a escalação ao suporte
Listas de erros por serviço
Toda referência de API traz uma página Tratamento de erros. Use-a para consultar um código que você recebeu. Produtos
Trilhos Brasil
Interfaces
Plataforma
Boas práticas
1. Use códigos de erro para tratamento programático
Códigos de erro são identificadores estáveis para automação. Mapeie códigos específicos para caminhos de resolução na sua integração. Tire os códigos da página de lista de erros da sua API.2. Registre erros com contexto
Registre a operação, o timestamp, o status, o código de erro estável e uma resposta com dados sensíveis removidos. Não registre credenciais, bearer tokens, dados pessoais ou campos sensíveis da requisição. Isso mantém o contexto útil para o suporte sem copiar segredos ou PII para os logs.3. Trate erros por campo
Quando a resposta carrega detalhe por campo, mostre essas mensagens aos seus usuários em vez de um erro genérico. O membro que carrega esse detalhe difere por API. Cada página de lista de erros nomeia o membro que a API dela envia.4. Implemente circuit breakers para integrações
Se você receber500, 502 ou 503 repetidos, use um padrão de circuit breaker para parar temporariamente de chamar o serviço com falha e evitar falhas em cascata.