Ler o erro da API antes de culpar alguém ou repetir

Apontar a culpa errada numa reunião de incidente custa minutos que a equipe passa investigando o lado que não falhou. O código de resposta orienta essa leitura, mas sozinho não determina quem causou o problema, nem se a chamada merece ser repetida.

A faixa 400 indica que o pedido não foi atendido por condições como formato, autenticação, permissão ou limite de uso; a configuração do servidor também pode estar envolvida. A faixa 500 informa falha no processamento pelo servidor ou por um intermediário, sem provar que o pedido estava correto.

Cruze o código com a mensagem, os registros e o contrato da API antes de atribuir responsabilidade. Três códigos merecem nome próprio: o 401 indica ausência de credencial válida, e o 403 indica recusa de acesso, sem provar por si só que a identidade foi confirmada.

O 429 diz que a chamada passou do teto combinado por período, e pode trazer a orientação Retry-After, o tempo antes de tentar de novo; repetir na mesma hora só piora.

Repita apenas falhas previstas como transitórias no contrato, com espera e teto. Um 503 pode ceder na próxima tentativa, mas um 422 recusado por validação falha igual, porque o problema está no pedido, não na rede.

Cada repetição desnecessária ainda consome cota, registro e atenção de quem está no incidente.

Nunca repita uma cobrança sem usar a mesma chave de idempotência, o identificador que evita repetir o efeito quando o fornecedor oferece essa garantia. Confira a validade dela e consulte a situação da operação se o resultado continuar incerto.

Quando a dependência cai de vez, insistir derruba o resto do sistema. O disjuntor evita esse colapso com quatro peças: teto de tentativas, e espera crescente com sorteio no intervalo, para os clientes não voltarem juntos.

A terceira peça é a abertura automática depois de N falhas, que devolve erro na hora; a quarta é a fila de mensagens mortas, onde fica o que falhou para inspeção.

Isso muda a primeira pergunta da reunião de incidente. Em vez de perguntar de quem é a culpa, peça a distribuição das respostas por faixa na última hora.

Um aumento de 400 pede verificar entrada, acesso e limites; um aumento de 500 pede investigar processamento e dependências.

Peça também quantas chamadas o sistema repete sozinho e com qual teto, e quem é avisado quando o disjuntor abre. Distribua a responsabilidade só depois de confrontar esses três números com os registros do incidente.

Se você guardar só cinco palavras, guarde estas. API é o balcão pelo qual outro sistema conversa com a retaguarda. Contrato é a promessa do que ela aceita e devolve. Breaking change é a mudança que quebra quem já integrou. Rate limit é o teto de chamadas por período. Disjuntor para de tentar depois de N falhas.

Trate mudança de contrato como alteração contratual, comunicada com prazo de aviso a quem consome. Aprove remover um campo só quando a medição mostrar uso zero, e confira se o erro devolvido diz o que aconteceu. A escolha do estilo de integração fica com o time; a decisão que cabe a você é o compromisso de compatibilidade.