Erros e códigos de estado

A chamada funciona em desenvolvimento. Agora está a escrever a parte que vai correr em produção – o bloco catch. Por si só, um erro HTTP de uma API de terceiros pouco esclarece: um código de estado a vermelho e nenhuma resposta óbvia à única pergunta que importa às 3 da manhã – o problema está no meu pedido, na minha chave, no meu plano ou nos servidores deles? E, destes erros, quais justificam repetir o pedido e quais devo apresentar ao utilizador?

O Lingo.dev responde com uma estrutura clara. Todos os erros dos pontos de acesso destas páginas, síncronos ou assíncronos, devolvem o mesmo objeto JSON, com um código de estado de uma tabela fixa. Já a API da plataforma em /v2 usa o formato normalizado de detalhes do problema; consulte Erros da API da plataforma. O código de estado não é um rótulo; é uma instrução: indica se deve corrigir o pedido, substituir a chave, carregar a conta, aguardar ou tentar novamente. Leia o código e saiba qual é o próximo passo. Um único mecanismo de tratamento de erros, baseado no código de estado, abrange toda a API.

Nesta página

• A estrutura dos erros
• Códigos de estado
• Que erros justificam uma nova tentativa
• 402 vs 429: dois limites diferentes
• Onde encontrar os erros de tarefas assíncronas
• Erros da API da plataforma

A estrutura dos erros#

Todas as respostas fora do intervalo 2xx têm o mesmo corpo: um objeto JSON com um único campo message que descreve o que correu mal.

{
  "message": "Invalid API key"
}

O contrato resume-se a isto. Não há uma estrutura envolvente a extrair nem formatos de erro específicos de cada ponto de acesso que exijam tratamento especial. Um 400 de /process/localize e um 404 de uma consulta de tarefa devolvem a mesma estrutura – só mudam o código de estado e o texto de message.

Códigos de estado#

Sete códigos de estado abrangem todas as respostas. Estão aqui agrupados por quem resolve o erro – porque esse agrupamento também define a sua política de novas tentativas.

Enviou algo que não pode ser processado no pedido (corrija o pedido, não o repita às cegas):

A sua organização atingiu um limite da conta (resolva na faturação):

Algo falhou do nosso lado (falha transitória – tente novamente):

Um 401 e um 403 parecem semelhantes, mas não são o mesmo problema: 401 significa que não conseguimos identificar quem fez a chamada; 403 significa que identificámos a chave, mas esta não tem autorização de acesso. A solução para 401 está na própria chave (substitua-a ou verifique-a); a solução para 403 está nas permissões de acesso da chave.

Que erros justificam uma nova tentativa#

Perante uma tabela de erros, a primeira pergunta de quem integra uma API com espírito crítico costuma ficar sem resposta: em quais destes casos devo tentar novamente? O agrupamento acima dá a resposta.

• 4xx – não repita às cegas. Um 400, 401, 403 ou 404 descreve uma condição no seu pedido. Repetir o mesmo pedido produz o mesmo erro. Corrija os dados de entrada, a chave ou o ID do recurso e volte a enviá-lo.
• 402 e 429 – aguarde e depois resolva o limite. Estes erros não são transitórios ao nível do pedido; o pedido seguinte esbarra no mesmo limite enquanto este não mudar. Pare de repetir pedidos em sucessão rápida, apresente o limite e resolva-o (carregue a conta ou mude para um plano superior).
• 500 – tente novamente com intervalos de espera progressivos. Esta é a única categoria verdadeiramente transitória. Um 500 pode significar que todos os modelos configurados excederam o tempo limite nessa chamada; uma nova tentativa pode encontrar um modelo a funcionar corretamente. Use intervalos de espera exponenciais e defina um número máximo de tentativas.

402 vs 429: dois limites diferentes#

Os dois códigos ao nível da conta parecem semelhantes – ambos dão a entender que "esgotou o que tinha" – e confundi-los leva quem desenvolve a procurar a solução errada. São limites distintos, com soluções distintas:

• 402 Payment Required – a organização atingiu o limite de créditos. Trata-se de um limite de faturação. A chamada seguinte continuará a falhar até que o estado de faturação da organização mude.
• 429 Too Many Requests – a organização atingiu a quota diária de tokens. Trata-se de um limite de consumo que se repõe e que pode aumentar mudando para um plano superior.

É por isso que deve distingui-los no mecanismo de tratamento de erros: um 402 exige que alguém tome uma medida na faturação; um 429 indica uma quota cuja reposição pode aguardar ou cujo limite pode aumentar mudando para um plano superior. Apresentar uma mensagem genérica de "problema de pagamento" em ambos os casos oculta a medida que o operador realmente precisa de tomar.

O corpo de um 402 é igual ao de qualquer outro erro – é o código de estado que indica que se trata de um limite de créditos:

{
  "message": "Organization has reached its credit limit"
}

Onde encontrar os erros de tarefas assíncronas#

Há uma distinção importante a fazer, pois marca o ponto em que um mecanismo baseado em códigos de estado deixa de ser a ferramenta certa.

Os códigos de estado desta página são ao nível do transporte: indicam se a API aceitou e conseguiu responder ao seu pedido HTTP. Um 202 da API assíncrona significa que o pedido foi aceite – não que a tradução tenha sido bem-sucedida. Uma tarefa assíncrona pode ser aceite sem problemas e ainda assim falhar mais tarde, quando um modelo excede o tempo limite a meio da execução. Essa falha não surge como um código de estado HTTP na chamada original; fica registada na própria tarefa.

Assim, as falhas assíncronas surgem em três locais, nenhum deles nesta tabela:

• Estado por tarefa. Quando o processamento de um idioma falha, a tarefa apresenta status: "failed" e um errorMessage. Consulte estados das tarefas.
• Estado do grupo. Quando o processamento de alguns idiomas é bem-sucedido e o de outros falha, o grupo apresenta partial – os resultados dos idiomas bem-sucedidos continuam a ser entregues. Consulte acompanhar um grupo de tarefas.
• Entrega por webhook. Uma falha é comunicada através de um evento translation.failed com um campo error. Consulte entrega por webhook.

Há mais uma distinção que costuma causar confusão: a falha de uma etapa não crítica do fluxo de processamento não faz falhar a tarefa. A tarefa é concluída com completed_with_warnings e avisos por etapa, em vez de um erro. Trata-se de uma questão de observabilidade do fluxo de processamento, não de um código de erro – consulte observar as execuções do fluxo de processamento.

Erros da API da plataforma#

A API da plataforma em https://api.lingo.dev/v2 responde aos erros de forma diferente. Devolve detalhes do problema segundo a RFC 9457, enviados como application/problem+json:

{
  "type": "https://lingo.dev/docs/api/errors/glossary-in-use",
  "status": 409,
  "title": "Glossary in use",
  "detail": "Glossary gls_1 cannot be deleted while 2 engines apply it. Detach it from those engines first.",
  "id": "gls_1",
  "engineCount": 2
}

• type identifica o problema. É uma ligação para a página específica desse problema, que lista os seus campos e os pontos de acesso que o devolvem. Baseie a lógica de tratamento em type.
• status repete o código de estado HTTP.
• title é um resumo breve, igual para todas as ocorrências de um mesmo tipo.
• detail indica o que aconteceu desta vez e o que fazer a seguir. Destina-se a uma pessoa, por isso apresente-o em vez de o analisar programaticamente.
• Os restantes membros contêm os dados desta ocorrência, como id e engineCount acima. detail é construído apenas a partir desses dados, pelo que um cliente pode apresentar o seu próprio texto, no seu idioma, a partir de type e destes campos.

Quando um pedido falha a validação, a resposta devolve 400 e lista cada valor inválido em errors, sob a forma de pares { "path", "message" }. Todos os pontos de acesso também podem responder com service-unavailable (503), caso em que é seguro repetir o pedido com intervalos de espera progressivos, e internal-server-error (500).

Cada código de estado segue uma regra:

Próximos passos#

Um mecanismo de tratamento de erros bem estruturado começa pelas duas questões que encontrará primeiro durante a integração – a autenticação e os pontos em que o trabalho assíncrono comunica o seu próprio resultado.