La llamada funciona en desarrollo. Ahora te toca escribir la parte que corre en producción: el bloque catch. Un error HTTP de una API de terceros, por sí solo, dice poco: un código de estado en rojo y ninguna respuesta clara a la única pregunta que importa a las 3 a. m.: ¿es mi solicitud, mi clave, mi plan o sus servidores? Y de todo eso, ¿qué conviene reintentar y qué hay que mostrarle al usuario?
Lingo.dev resuelve eso con estructura. Todos los errores, de cualquier endpoint, síncrono o asíncrono, vuelven con el mismo objeto JSON y un código de estado tomado de una sola tabla fija. El código de estado no es una etiqueta: es una instrucción. Te dice si tienes que corregir la solicitud, rotar la clave, recargar la cuenta, bajar el ritmo o reintentar. Lee el código y sabrás cuál es el siguiente paso. Un único manejador de errores, basado en el estado, cubre toda la API.
En esta página
- La estructura del error
- Códigos de estado
- Qué errores reintentar
- 402 vs. 429: dos límites distintos
- Dónde aparecen los errores de trabajos asíncronos
La estructura del error#
Todas las respuestas fuera del rango 2xx tienen el mismo cuerpo: un objeto JSON con un único campo message que describe qué salió mal.
{
"message": "Invalid API key"
}Ese es todo el contrato. No hay ningún envoltorio que desarmar ni formatos de error por endpoint que requieran casos especiales. Un 400 de /process/localize y un 404 al consultar un trabajo devuelven la misma estructura; solo cambian el código de estado y el texto de message.
Haz match con el código de estado, no con el texto del mensaje
El código de estado HTTP es la señal estable: basa ahí tu manejo de errores. La cadena message está escrita para una persona que lee un log; trátala como una descripción, no como un código de error legible por máquina, y no hagas match con su redacción exacta.
Códigos de estado#
Siete códigos de estado cubren todas las respuestas. Aquí están agrupados según quién los resuelve, porque esa agrupación también define tu política de reintentos.
Enviaste algo que la solicitud no puede resolver (corrige la solicitud, no reintentes a ciegas):
| Estado | Significado |
|---|---|
400 Bad Request | Falló la validación de la solicitud: falta un campo, hay un idioma no válido, una callbackUrl HTTP (no HTTPS) o un payload mal formado. |
401 Unauthorized | Falta el encabezado X-API-Key o no es válido. Consulta Authentication. |
403 Forbidden | La clave es válida, pero no tiene acceso al recurso solicitado. |
404 Not Found | El recurso —un motor, un trabajo o un grupo de trabajos— no existe. |
Tu organización alcanzó un límite de cuenta (se resuelve en facturación):
| Estado | Significado |
|---|---|
402 Payment Required | La organización alcanzó su límite de crédito. |
429 Too Many Requests | La organización alcanzó su cuota diaria de tokens. Mejora el plan para aumentar el límite. |
Algo falló de nuestro lado (transitorio: reintenta):
| Estado | Significado |
|---|---|
500 Internal Server Error | Un fallo inesperado: un error de base de datos o una llamada de traducción que falló en todos los modelos configurados en el motor. |
Un 401 y un 403 pueden parecerse, pero no apuntan al mismo problema: 401 significa que no pudimos identificar al cliente que hace la llamada; 403 significa que sí identificamos la clave, pero no tiene permiso para entrar. La solución para 401 está en la propia clave (rótala o revísala); la solución para 403 está en los permisos de esa clave.
Qué errores reintentar#
La primera pregunta de cualquier integrador escéptico frente a una tabla de errores suele ser la que casi nunca responde: ¿cuáles de estos errores conviene reintentar? La agrupación anterior es la respuesta.
- 4xx: no reintentes a ciegas. Un
400,401,403o404describe una condición en tu solicitud. Si repites exactamente la misma solicitud, obtendrás exactamente el mismo error. Corrige la entrada, la clave o el id del recurso y luego vuelve a enviarla. - 402 y 429: baja el ritmo y luego resuelve el límite. No son errores transitorios a nivel de solicitud; la siguiente solicitud se va a topar con el mismo muro hasta que cambie el límite subyacente. Deja de reintentar en un loop cerrado, muestra el límite y resuélvelo (recarga saldo o mejora el plan).
- 500: reintenta con backoff. Esta es la única clase que realmente es transitoria. Un
500puede significar que todos los modelos configurados agotaron el tiempo de espera en esa llamada; un reintento podría caer en un modelo sano. Usa backoff exponencial y un tope de reintentos.
La API asíncrona reporta los resultados de otra manera
Esta política de reintentos aplica a llamadas sincrónicas que haces tú mismo. La API de localización asíncrona no te devuelve un código de estado con el resultado del trabajo: una POST devuelve 202 en cuanto se acepta la solicitud, y cada idioma de destino corre como un trabajo independiente a través de flujos de trabajo duraderos en segundo plano. En lugar de capturar un código de estado en tu llamada original, consultas el trabajo o recibes un webhook con el resultado. Consulta dónde aparecen los errores de trabajos asíncronos.
402 vs. 429: dos límites distintos#
Los dos códigos a nivel de cuenta suenan parecidos: ambos se leen como "te quedaste sin". Pero confundirlos lleva al desarrollador a la solución equivocada. Son límites distintos y se resuelven de forma distinta:
402 Payment Required: la organización alcanzó su límite de crédito. Este es un límite de facturación. La siguiente llamada va a seguir fallando hasta que cambie el estado de facturación de tu organización.429 Too Many Requests: la organización alcanzó su cuota diaria de tokens. Este es un tope de uso que se restablece, y puedes aumentarlo mejorando el plan.
La razón para mantenerlos separados en tu manejador: un 402 requiere una acción de facturación que realiza una persona; un 429 es una cuota que puedes esperar a que se restablezca o aumentar mejorando el plan. Enviar ambos a un mensaje genérico de "problema de pago" oculta qué palanca tiene que mover realmente el operador.
El cuerpo de un 402 se ve igual que cualquier otro error; lo que te dice que se trata de un límite de crédito es el código de estado:
{
"message": "Organization has reached its credit limit"
}Dónde aparecen los errores de trabajos asíncronos#
Aquí conviene trazar una línea, porque es el punto donde un manejador basado en códigos de estado deja de ser la herramienta correcta.
Los códigos de estado de esta página son de nivel de transporte: describen si la API aceptó y pudo atender tu solicitud HTTP. Un 202 de la API asíncrona significa que tu solicitud fue aceptada, no que la traducción haya salido bien. Un trabajo asíncrono puede aceptarse sin problema y aun así fallar más tarde, por ejemplo, si un modelo agota el tiempo de espera a mitad de ejecución. Ese fallo no aparece como un código de estado HTTP en tu llamada original; queda registrado en el propio trabajo.
Así que los fallos asíncronos aparecen en tres lugares, y ninguno está en esta tabla:
- Estado por trabajo. Un idioma fallido lleva
status: "failed"y unerrorMessageen el trabajo. Consulta job statuses. - Estado del grupo. Cuando algunos idiomas terminan bien y otros fallan, el grupo reporta
partial; los idiomas que sí salieron bien igual se entregan. Consulta tracking a job group. - Entrega de webhooks. Un fallo se entrega como un evento
translation.failedcon un campoerror. Consulta webhook delivery.
Hay una distinción más que suele confundir: si falla una etapa no crítica del pipeline, no falla el trabajo. El trabajo se completa con completed_with_warnings y advertencias por paso, en lugar de un error. Eso es un tema de observabilidad del pipeline, no un código de error. Consulta observe pipeline runs.
Siguientes pasos#
Un buen manejador de errores empieza por los dos códigos que verás primero durante la integración: autenticación y los puntos donde el trabajo asíncrono reporta su propio resultado.
