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:
{
"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:
{
"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 HTTP | Causa típica | Próxima ação |
|---|---|---|
| 400 | A 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. |
| 401 | Credenciais ausentes, inválidas ou expiradas. | Carregue a chave desejada ou renove a sessão do usuário. |
| 402 | Cré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. |
| 403 | Falta 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. |
| 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 estado atual do recurso. Envie os artefatos ausentes, conclua o trabalho em execução ou atualize uma revisão encerrada, conforme indicado. |
| 413 | Um 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. |
| 422 | A 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. |
| 429 | Um 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. |
| 5xx | Um 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.