Errores y códigos de estado

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

Verifica el estado HTTP antes de decodificar una respuesta exitosa. La API en https://api.lingo.dev/v2 informa los fallos mediante detalles del problema en JSON. Un trabajo obtenido correctamente puede indicar que hubo tareas fallidas, así que revisa también su estado.

Lee una respuesta de error #

Las respuestas de error usan 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 corresponde a un trabajo de localización que no se encontró:

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 de type identifica el problema. Consulta el catálogo de errores de la API para conocer los campos y 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 pasa la validación devuelve 400 Solicitud incorrecta con type: "about:blank". Cuando hay detalles de validación disponibles, errors enumera los valores de path y 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"
    }
  ]
}

La ruta comienza con la parte de la solicitud que se está validando, como payload, seguida de nombres de propiedades e índices de arreglos que comienzan 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 recuperarte del error #

Estado HTTPCausa habitualSiguiente acción
400La solicitud no se ajusta al esquema de la ruta.Corrige la ruta, los parámetros de consulta, los encabezados o el cuerpo según los detalles de validación recibidos.
401Credenciales faltantes, no válidas o vencidas.Carga la clave correspondiente o renueva la sesión del usuario.
402Créditos insuficientes, funciones no disponibles en el plan o una clave de servicio deshabilitada tras una reducción de permisos de RBAC.Consulta la condición indicada y cumple el requisito de la cuenta o del plan.
403Falta un permiso o una identidad de usuario requerida, o hay una restricción impuesta por un indicador de función.Verifica 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.Verifica 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. Carga los artefactos faltantes, finaliza el trabajo 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; las cargas de artefactos admiten hasta 25 MiB cada una.
422La solicitud es estructuralmente 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 alcanzó un límite de uso o de operaciones.Respeta el tiempo de reintento indicado en el problema, si se proporciona; de lo contrario, verifica el límite de la cuenta antes de volver a intentarlo.
5xxUn servidor o una dependencia no pudo completar la solicitud.Conserva los ID del recurso y de la solicitud; vuelve a intentarlo solo conforme a la semántica de la operación.

detail explica el fallo específico; el 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 su estado HTTP y el texto legible de la respuesta para el diagnóstico, sin registrar secretos.

Reintenta el envío de una solicitud 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. Consulta ese trabajo antes de decidir crear otro. Las cargas usan exactamente los bytes identificados por su dirección SHA-256; completa las cargas faltantes antes de iniciar el trabajo. Repetir /start actúa sobre el mismo trabajo.

Las verificaciones 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 resuelve un límite de la cuenta.

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

Un estado HTTP 200 de GET /v2/localization/jobs/:id significa que se obtuvo el trabajo. Su status._tag aún puede ser Failed. Consulta status.message, el estado de cada destino y las advertencias y los fallos de las etapas.

Los destinos completados siguen disponibles para descargar aunque otro destino falle. Consérvalos y, después de corregir la causa, envía solo el trabajo que necesite regenerarse. Si se agota el tiempo de espera durante el sondeo del cliente, el trabajo no se cancela.

El aprovisionamiento tiene sus propios resultados por tipo y métodos de recuperación. Las decisiones de revisión tienen sus propios errores de revisión cerrada y de edición no válida. Al recuperarte de un error, ten en cuenta el estado de esos recursos en lugar de tomar cada fallo como un motivo para repetir la escritura original.