Errores y códigos de estado

Interpreta las respuestas de error de la API, recupera las solicitudes fallidas y distingue los fallos HTTP de los fallos en los trabajos de traducción.

Comprueba el código de estado HTTP antes de descodificar una respuesta correcta. La API en https://api.lingo.dev/v2 comunica los fallos mediante detalles del problema en formato JSON. Un trabajo recuperado correctamente puede describir tareas fallidas, así que comprueba también su estado.

Interpreta una respuesta de error #

Las respuestas de error utilizan Content-Type: application/problem+json. Los campos habituales son type, title, status y detail; los problemas con nombre también incluyen campos que identifican el recurso afectado o la solución.

Este ejemplo muestra un trabajo de localización que falta:

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

El URI type identifica el problema. Consulta el catálogo de errores de la API para conocer los campos y los puntos de conexión de cada problema con nombre. Conserva el URI devuelto sin cambios al almacenar o clasificar un error.

Corrige una solicitud no válida #

Una solicitud que no supera la validación devuelve 400 Solicitud incorrecta con type: "about:blank". Cuando hay detalles de validación disponibles, errors enumera los campos path y message de cada incidencia:

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

La ruta comienza con la parte de la solicitud que se está validando, como payload, seguida de los nombres de las propiedades y los índices de las matrices, que empiezan en cero. Este ejemplo identifica source en la primera entrada de documents del cuerpo de la solicitud. Corrige el valor indicado conforme al esquema del punto de conexión antes de volver a enviar la solicitud. about:blank es un tipo de problema genérico, por lo que no tiene una entrada en el catálogo de errores con nombre.

Elige cómo resolver el fallo #

Estado HTTPCausa habitualSiguiente acción
400La solicitud no se ajusta al esquema de la ruta.Corrige la ruta, los parámetros de consulta, las cabeceras o el cuerpo según los detalles de validación proporcionados.
401Credenciales ausentes, no válidas o caducadas.Carga la clave que corresponda o renueva la sesión de usuario.
402Créditos insuficientes, funciones no disponibles en el plan o una clave de servicio deshabilitada tras una reducción de permisos RBAC.Consulta la condición indicada y cumple el requisito de la cuenta o del plan.
403Falta un permiso o una identidad de usuario obligatoria, o hay una restricción impuesta por un indicador de función.Comprueba quién realiza la llamada y los requisitos de acceso de la operación.
404El recurso no existe o no es visible para quien realiza la llamada.Comprueba el identificador, la organización y los permisos del recurso.
409La operación entra en conflicto con el estado del recurso.Consulta el estado actual del recurso. Sube los artefactos que faltan, finaliza las tareas en ejecución o actualiza una revisión cerrada, según se indique.
413Una carga o el cuerpo de una solicitud supera el límite de tamaño.Reduce los datos de entrada o divide el trabajo; cada carga de artefactos admite hasta 25 MiB.
422La estructura de la solicitud es válida, pero incumple las restricciones de una operación.Corrige la condición indicada, como una edición no válida de una revisión o una clave de idempotencia reutilizada.
429Se ha alcanzado un límite de uso o de operaciones.Respeta el tiempo de reintento indicado en el problema, si se proporciona; de lo contrario, comprueba el límite de la cuenta antes de volver a intentarlo.
5xxUn servidor o una dependencia no ha podido completar la solicitud.Conserva los ID del recurso y de la solicitud; vuelve a intentarlo solo si la semántica de la operación lo permite.

detail explica el fallo concreto; el código de estado por sí solo no ofrece una clasificación completa. Las respuestas de un proxy o de un fallo de red pueden no incluir un cuerpo con los detalles del problema. Conserva el estado HTTP y el texto legible de la respuesta para facilitar el diagnóstico, sin registrar secretos.

Vuelve a intentar un envío de localización #

Guarda el valor de Idempotency-Key de la solicitud de creación antes de enviarla. Si se pierde la respuesta, repite la misma solicitud de creación con esa clave para recuperar el trabajo original. Una clave nueva crea un trabajo nuevo.

Una vez creado el trabajo, guarda su ID. Consúltalo antes de decidir si crear otro. Las cargas utilizan los bytes exactos identificados por su dirección SHA-256; completa las cargas que falten antes de iniciar el trabajo. Repetir /start actúa sobre el mismo trabajo.

Las comprobaciones de admisión se realizan al iniciar el trabajo. DailyTokenLimitReached o la falta de créditos dejan el trabajo pendiente y disponible para iniciarlo más adelante, una vez resuelta la condición de la cuenta. Crear trabajos nuevos una y otra vez no soluciona un límite de la cuenta.

Distingue entre un fallo de la solicitud y un fallo del trabajo #

Un estado HTTP 200 de GET /v2/localization/jobs/:id significa que se ha recuperado el trabajo. Su status._tag puede seguir siendo Failed. Consulta status.message, el estado de cada destino y las advertencias y los fallos de las etapas.

Los destinos completados siguen disponibles para su descarga aunque falle otro destino. Consérvalos y, tras corregir la causa, envía solo el trabajo que necesite regenerarse. Que se agote el tiempo de espera de las consultas periódicas del cliente no cancela el trabajo.

El aprovisionamiento tiene sus propios resultados por tipo y procedimientos de recuperación. Las decisiones de revisión tienen sus propios errores de revisión cerrada y edición no válida. Ten en cuenta el estado de esos recursos al resolver un fallo, en lugar de considerar cada fallo un motivo para repetir la operación de escritura original.