Erros e códigos de estado

Interprete as respostas de problema da API, recupere solicitações com falha e diferencie falhas HTTP de falhas na execução da tradução.

Verifique o estado HTTP antes de decodificar uma resposta bem-sucedida. A API em https://api.lingo.dev/v2 informa falhas por meio de detalhes de problema em JSON. Mesmo um trabalho consultado com sucesso pode indicar uma falha na execução, por isso verifique também o estado dele.

Leia uma resposta de problema #

As respostas de problema usam Content-Type: application/problem+json. Os campos comuns são type, title, status e detail; os problemas nomeados também contêm campos que identificam o recurso afetado ou a correção necessária.

Este exemplo mostra um trabalho de localização não encontrado:

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"
}

A URI em type identifica o problema. Consulte o catálogo de erros da API para ver os campos e endpoints de cada problema nomeado. Mantenha a URI retornada inalterada ao armazenar ou classificar um erro.

Corrija uma solicitação inválida #

Uma solicitação que não passa na validação retorna 400 Solicitação inválida com type: "about:blank". Quando há detalhes de validação disponíveis, errors lista 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 com a parte da solicitação que está sendo validada, como payload, seguida dos nomes das propriedades e dos índices de arrays, contados a partir de zero. Este exemplo identifica source na primeira entrada de documents no corpo da solicitação. Corrija o valor indicado de acordo com o esquema do endpoint antes de enviar novamente. about:blank é um tipo genérico de problema, por isso não tem uma entrada no catálogo de erros nomeados.

Escolha a ação de recuperação #

Estado HTTPCausa típicaPróxima ação
400A solicitação 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 informados.
401Credenciais ausentes, inválidas ou expiradas.Carregue a chave desejada ou renove a sessão do usuário.
402Créditos insuficientes, recursos indisponíveis no plano ou uma chave de serviço desativada após uma redução de permissões de RBAC.Consulte a condição indicada e atenda ao requisito da conta ou do plano.
403Falta de permissão, exigência de uma identidade de usuário ou restrição por sinalizador de recurso.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 estado atual do recurso. Envie os artefatos ausentes, conclua o trabalho em execução ou atualize uma revisão encerrada, conforme indicado.
413Um envio ou o corpo de uma solicitação excede o limite de tamanho.Reduza os dados de entrada ou divida o trabalho; cada envio de artefato permite até 25 MiB.
422A solicitação é estruturalmente válida, mas viola as restrições de uma operação.Corrija a condição indicada, como uma edição inválida na revisão ou uma chave de idempotência reutilizada.
429Um limite de consumo ou de operação foi atingido.Respeite o prazo para nova tentativa informado no problema; se não houver um prazo, verifique o limite da conta antes de tentar novamente.
5xxUm servidor ou uma dependência não conseguiu concluir a solicitação.Guarde os IDs do recurso e da solicitação; 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 oferece uma classificação completa. Respostas de um proxy ou decorrentes de uma falha de rede podem não conter um corpo de problema. Preserve o estado HTTP e o texto legível da resposta para diagnóstico, sem registrar segredos.

Repita um envio de localização #

Salve Idempotency-Key da solicitação de criação antes de enviá-la. Se a resposta se perder, repita a mesma solicitação de criação com essa chave para recuperar o trabalho original. Uma nova chave cria um novo trabalho.

Após a criação, salve o ID do trabalho. Consulte esse trabalho antes de decidir criar outro. Os envios usam exatamente os bytes identificados pelo respectivo endereço SHA-256; conclua os envios que faltam antes de iniciar. Repetir /start atua sobre o mesmo trabalho.

As verificações de admissão ocorrem no início da execução. DailyTokenLimitReached ou créditos insuficientes deixam o trabalho pendente, disponível para ser iniciado mais tarde, assim que a condição da conta for resolvida. Criar novos trabalhos repetidamente não resolve um limite da conta.

Diferencie uma falha na solicitação de uma falha na execução do trabalho #

Uma resposta HTTP 200 de GET /v2/localization/jobs/:id significa que o trabalho foi consultado com sucesso. Ainda assim, 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 download mesmo se outro destino falhar. Guarde-os e, após corrigir a causa, envie apenas o trabalho que precisa ser gerado novamente. Se o tempo limite das consultas periódicas do cliente for atingido, o trabalho não será cancelado.

O provisionamento tem seus próprios resultados por tipo e procedimentos de recuperação. As decisões de revisão têm seus próprios erros de revisão encerrada e edição inválida. Use o estado desses recursos para orientar a recuperação, em vez de tratar cada falha como motivo para repetir a gravação original.