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:
{
"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:
{
"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 HTTP | Causa habitual | Ação seguinte |
|---|---|---|
| 400 | O 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. |
| 401 | Credenciais em falta, inválidas ou expiradas. | Carregue a chave pretendida ou renove a sessão do utilizador. |
| 402 | Cré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. |
| 403 | Falta 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. |
| 404 | O 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. |
| 409 | A 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. |
| 413 | Um 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. |
| 422 | O 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. |
| 429 | Foi 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. |
| 5xx | Um 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.