--- title: "Errores" description: "Gestión de fallos de la API de AI Glot mediante códigos de error estables, IDs de solicitud, guías de reintento y explicaciones detalladas para cada error documentado." canonical: "https://ai-glot.com/docs/es/api/errors" updated: "2026-08-12" --- # Errores Cualquier fallo de la API utiliza una única estructura de respuesta. Realice la bifurcación de la lógica basándose en `error.code`, nunca en el mensaje legible para humanos. ```json title="Ejemplo de error" { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "This credential is missing the batches:write scope.", "docs_url": "https://ai-glot.com/docs/api/errors#insufficient_scope" }, "request_id": "req_example" } ``` ## Códigos de estado | Estado | Significado | Qué hacer | | ------- | ---------------------------------------------------- | --------------------------------------------- | | 400 | Solicitud mal formada o campo desconocido | Corregir la solicitud | | 401 | Credencial ausente, inválida, caducada o revocada | Sustituirla o renovarla | | 403 | Autenticado pero sin permisos | Otorgar el scope o la funcionalidad requerida | | 404 | Recurso ausente o fuera de este espacio de trabajo | Verificar el ID y el espacio de trabajo | | 409 | El estado actual entra en conflicto con la solicitud | Leer el recurso y decidir la acción | | 413 | Cuerpo de la solicitud demasiado grande | Enviar un cuerpo más pequeño | | 422 | Valor bien formado pero inválido | Corregir el valor indicado | | 429 | Límite de tasa superado | Esperar al `Retry-After` | | 500/503 | AI Glot falló o no está disponible temporalmente | Reintentar con backoff | **Corregir antes de reintentar** La mayoría de las respuestas 400, 401, 403, 404, 409, 413 y 422 requieren un cambio en la credencial, el identificador, el estado o la solicitud. **Reintentar de forma segura** Reintente el error 429 tras el tiempo indicado en `Retry-After`; reintente los errores 500 y 503 con backoff exponencial y jitter aleatorio. > **Note** > > Conserve el `request_id` en los logs y mensajes de soporte. Permite identificar la solicitud en el servidor sin exponer su clave de API ni el contenido de los CSV. ## Códigos de autenticación y permisos ### authentication\_required No se envió ninguna credencial bearer. Añada el encabezado `Authorization`. ### invalid\_api\_key La clave está mal formada o es desconocida. Compruebe que se haya copiado el valor completo de `aig_live_…`. ### api\_key\_expired La clave ha llegado a su fecha de caducidad configurada. Cree una nueva o utilice un reemplazo. ### api\_key\_revoked Un administrador revocó o rotó esta clave. Actualice la integración con una credencial activa. ### insufficient\_scope La credencial se autenticó correctamente, pero carece del scope requerido para esta operación. ### feature\_not\_available El plan del espacio de trabajo o la versión actual de la plataforma no incluyen la funcionalidad solicitada. ### admin\_required Solo un administrador del espacio de trabajo puede realizar esta operación. ## Códigos de solicitud ### invalid\_request La solicitud no puede analizarse o no coincide con el contrato del endpoint. ### unknown\_field No se reconoce una propiedad del cuerpo JSON. Corrija la ortografía en lugar de eliminar la validación. Los parámetros de _consulta_ (query) no reconocidos nunca producen este error; se ignoran, por lo que un filtro mal escrito devuelve un `200` sin filtrar. ### invalid\_parameter Un parámetro tiene un tipo, rango o formato incorrecto. ### invalid\_cursor El cursor de paginación no es válido. Vuelva a utilizar el `next_cursor` exactamente como fue devuelto. ### request\_too\_large El cuerpo de la solicitud excede el límite estricto del endpoint. ## Códigos de recurso y estado ### batch\_not\_found Ninguna traducción visible tiene ese ID. Los recursos en otro espacio de trabajo devuelven intencionadamente el mismo error. ### glossary\_not\_found No existe un glosario para ese par de idiomas. ### resource\_not\_found El recurso o la ruta solicitados no existen. ### glossary\_already\_exists Ya existe un glosario para este par de idiomas. Actualícelo en lugar de crear otro. ### result\_not\_ready La traducción no ha finalizado, por lo que aún no se puede descargar el resultado. ### batch\_not\_editable El estado actual de la traducción no permite el cambio de mantenimiento solicitado. ## Códigos de idioma y glosario ### language\_not\_supported La etiqueta está fuera del catálogo admitido. Consulte [`GET /v1/languages`](/docs/api/languages/list). ### invalid\_language\_pair El identificador del par de idiomas no puede dividirse en dos etiquetas BCP 47 admitidas. ### glossary\_term\_limit\_reached El recuento de términos resultante superaría el límite permitido por el plan del espacio de trabajo. La actualización es atómica; no se ha modificado nada. ### glossary\_limit\_reached El espacio de trabajo ha alcanzado el número máximo de glosarios permitidos para el plan actual. ### invalid\_glossary\_terms Una o más entradas del glosario están vacías, incompletas o son inválidas. ## Códigos de servicio ### rate\_limited La credencial ha superado la ventana de tasa de solicitudes. Espere al `Retry-After` y luego reintente con jitter. ### internal\_error AI Glot ha fallado inesperadamente. Reintente con backoff y conserve el `request_id`. ### service\_unavailable Un servicio requerido no está disponible temporalmente. Reintente con backoff.