Erros e códigos de estado

Interprete as respostas de erro da API, recupere de falhas nos pedidos e distinga as falhas HTTP das falhas no trabalho de tradução.

Verifique o estado HTTP antes de descodificar uma resposta bem-sucedida. A API em https://api.lingo.dev/v2 comunica as falhas através de detalhes do problema em JSON. Mesmo que um trabalho seja obtido com êxito, pode indicar uma falha na execução, pelo que deve verificar também o respetivo estado.

Ler uma resposta de erro #

As respostas de erro utilizam Content-Type: application/problem+json. Os campos mais comuns são type, title, status e detail; os problemas com nome específico incluem também campos que identificam o recurso afetado ou a correção necessária.

Este exemplo mostra um trabalho de localização inexistente:

json
{
  "type": "https://lingo.dev/docs/api/errors/localization-job-not-found",
  "title": "Localization job not found",
  "status": 404,
  "detail": "Localization job lfr_example not found.",
  "id": "lfr_example"
}

O URI type identifica o problema. Consulte o catálogo de erros da API para conhecer os campos e os pontos de acesso de cada problema com nome específico. Ao guardar ou classificar um erro, mantenha o URI devolvido inalterado.

Corrigir um pedido inválido #

Um pedido que não passe na validação devolve 400 Pedido inválido com type: "about:blank". Quando estão disponíveis detalhes de validação, errors apresenta os campos path e message de cada problema:

json
{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Request validation failed",
  "errors": [
    {
      "path": ["payload", "documents", 0, "source"],
      "message": "Expected a JSON object"
    }
  ]
}

O caminho começa pela parte do pedido que está a ser validada, como payload, seguida dos nomes das propriedades e dos índices das matrizes, que começam em zero. Este exemplo identifica source na primeira entrada de documents no corpo do pedido. Corrija o valor indicado de acordo com o esquema do ponto de acesso antes de voltar a enviar o pedido. about:blank é um tipo de problema genérico, pelo que não tem uma entrada no catálogo de erros com nome específico.

Escolher a ação de recuperação #

Estado HTTPCausa habitualAção seguinte
400O pedido não corresponde ao esquema da rota.Corrija o caminho, os parâmetros de consulta, os cabeçalhos ou o corpo com base nos detalhes de validação comunicados.
401Credenciais em falta, inválidas ou expiradas.Carregue a chave pretendida ou renove a sessão do utilizador.
402Créditos insuficientes, funcionalidades indisponíveis no plano ou uma chave de serviço desativada após uma redução de permissões RBAC.Consulte a condição indicada e satisfaça o requisito da conta ou do plano.
403Falta de permissão, ausência de uma identidade de utilizador obrigatória ou uma restrição imposta por um sinalizador de funcionalidade.Verifique quem faz a chamada e os requisitos de acesso da operação.
404O recurso não existe ou não está visível para quem faz a chamada.Verifique o identificador, a organização e as permissões do recurso.
409A operação entra em conflito com o estado do recurso.Consulte o recurso no seu estado atual. Carregue os artefactos em falta, conclua o trabalho em execução ou atualize uma revisão encerrada, conforme indicado.
413Um carregamento ou o corpo de um pedido excede o limite de tamanho.Reduza os dados de entrada ou divida o trabalho; cada carregamento de artefacto permite até 25 MiB.
422O pedido é estruturalmente válido, mas viola as restrições de uma operação.Corrija a condição indicada, como uma alteração inválida numa revisão ou a reutilização de uma chave de idempotência.
429Foi atingido um limite de consumo ou de operações.Respeite o momento indicado no problema para uma nova tentativa, se fornecido; caso contrário, verifique o limite da conta antes de tentar novamente.
5xxUm servidor ou uma dependência não conseguiu concluir o pedido.Guarde os IDs do recurso e do pedido; tente novamente apenas de acordo com a semântica da operação.

detail explica a falha específica; o estado, por si só, não constitui uma classificação completa. As respostas provenientes de um proxy ou de uma falha de rede podem não conter detalhes do problema no corpo. Conserve o estado HTTP e o texto legível da resposta para diagnóstico, sem registar segredos.

Repetir o envio de um pedido de localização #

Guarde a Idempotency-Key do pedido de criação antes de o enviar. Se a resposta se perder, repita o mesmo pedido de criação com essa chave para obter o trabalho original. Uma nova chave cria um novo trabalho.

Após a criação, guarde o ID do trabalho. Consulte esse trabalho antes de decidir criar outro. Os carregamentos utilizam exatamente os bytes identificados pelo respetivo endereço SHA-256; conclua os carregamentos em falta antes de iniciar o trabalho. Repetir /start atua sobre o mesmo trabalho.

As verificações de admissão são efetuadas ao iniciar o trabalho. DailyTokenLimitReached ou créditos insuficientes deixam o trabalho pendente, disponível para ser iniciado mais tarde, assim que a condição da conta estiver resolvida. Criar novos trabalhos repetidamente não resolve um limite da conta.

Distinguir uma falha no pedido de uma falha no trabalho #

Uma resposta HTTP 200 de GET /v2/localization/jobs/:id significa que o trabalho foi obtido. Ainda assim, o seu status._tag pode ser Failed. Consulte status.message, o estado de cada destino e os avisos e falhas das etapas.

Os destinos concluídos continuam disponíveis para transferência, mesmo que outro destino falhe. Guarde-os e, depois de corrigir a causa, envie apenas o trabalho que precisa de ser gerado novamente. Atingir o tempo limite de consulta periódica do cliente não cancela o trabalho.

O aprovisionamento tem os seus próprios resultados por tipo e procedimentos de recuperação. As decisões de revisão têm os seus próprios erros de revisão encerrada e de edição inválida. Baseie a recuperação no estado desses recursos, em vez de considerar cada falha um motivo para repetir a operação de escrita original.