Erros e novas tentativas

As APIs da Alkax utilizam códigos de estado HTTP para o resultado principal e corpos de resposta estruturados para os detalhes legíveis por máquina e por pessoas.

Códigos de estado comuns

Estado	Significado	Ação do cliente
400	Pedido inválido ou falha de validação	Corrija o pedido antes de o reenviar
401	Credencial em falta, malformada, inválida, expirada ou revogada	Substitua a credencial
402	É necessária uma subscrição paga	Ative ou renove a subscrição do titular do projeto
403	Autenticado, mas sem permissão	Verifique os âmbitos, o acesso e a titularidade do tenant
404	Recurso não encontrado ou não visível para este tenant	Verifique o ID estável; não faça sondagens repetidas
409	Conflito de ciclo de vida, duplicação ou idempotência	Leia o recurso atual e reconcilie
429	Limite de frequência ou franquia mensal do plano atingidos	Respeite Retry-After, reduza a utilização ou atualize o plano
5xx	Falha temporária do servidor	Repita um número limitado de vezes com espera exponencial

Padrão seguro de novas tentativas

1. Defina um tempo limite para o pedido.
2. Repita apenas falhas de rede, respostas 429 e resultados 5xx transitórios documentados.
3. Reutilize a mesma chave de idempotência ao repetir o mesmo pedido lógico de criação.
4. Adicione espera exponencial com variação aleatória.
5. Pare após um número limitado de tentativas e apresente a falha para revisão.

Nunca repita uma resposta 400 sem alterar o pedido. Evite criar uma nova chave de idempotência apenas porque a primeira resposta se perdeu; isso pode transformar uma operação pretendida em duas.

Mensagens traduzidas

Algumas APIs traduzem as mensagens legíveis por pessoas com base em Accept-Language. Não faça a lógica do programa depender de texto traduzido. Guarde antes o estado, o ID estável do recurso e o código de erro legível por máquina.