Errores
Gestiona los errores de la API de AI Glot mediante códigos de error estables, ID de solicitud, pautas de reintento y explicaciones detalladas para cada error documentado.
Todos los errores de la API usan el mismo formato. Basa la lógica en error.code, nunca en el mensaje legible.
{
"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 | Corrige la solicitud |
| 401 | Credencial ausente, no válida, caducada o revocada | Sustitúyela o renuévala |
| 403 | Autenticación correcta, pero sin permisos | Concede el ámbito o la función necesarios |
| 404 | El recurso no existe o está fuera de este espacio de trabajo | Comprueba el ID y el espacio de trabajo |
| 409 | El estado actual entra en conflicto con la solicitud | Consulta el recurso y decide cómo proceder |
| 413 | El cuerpo de la solicitud es demasiado grande | Envía un cuerpo más pequeño |
| 422 | Valor bien formado, pero no válido | Corrige el valor indicado |
| 429 | Se ha alcanzado el límite de solicitudes | Espera a Retry-After |
| 500/503 | AI Glot ha fallado o no está disponible temporalmente | Reintenta con esperas progresivas |
Códigos de autenticación y permisos
authentication_required
No se ha enviado ninguna credencial de tipo bearer. Añade el encabezado Authorization.
invalid_api_key
La clave tiene un formato incorrecto o no se reconoce. Comprueba que has copiado el valor aig_live_… completo.
api_key_expired
La clave ha alcanzado la fecha de caducidad configurada. Crea o utiliza otra.
api_key_revoked
Un administrador ha revocado o renovado esta clave. Actualiza la integración con una credencial activa.
insufficient_scope
La credencial se ha autenticado, pero no tiene el ámbito necesario para esta operación.
feature_not_available
El plan del espacio de trabajo o la versión actual de la plataforma no incluye la función solicitada.
admin_required
Solo un administrador del espacio de trabajo puede realizar esta operación.
Códigos de solicitud
invalid_request
No se puede analizar la solicitud o no cumple el contrato del endpoint.
unknown_field
No se reconoce una propiedad del cuerpo JSON. Corrige su escritura en lugar de eliminar la validación. Los parámetros de consulta no reconocidos no generan 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. Vuelve a usar next_cursor exactamente tal como se devolvió.
request_too_large
El cuerpo de la solicitud supera el límite máximo del endpoint.
Códigos de recursos y estados
batch_not_found
No hay ninguna traducción visible con ese ID. Los recursos de otro espacio de trabajo devuelven intencionadamente el mismo error.
glossary_not_found
No existe ningún glosario para esa combinación de idiomas.
resource_not_found
El recurso o la ruta solicitados no existen.
glossary_already_exists
Ya existe un glosario para esa combinación de idiomas. Actualízalo en lugar de crear otro.
result_not_ready
La traducción aún no ha terminado, por lo que todavía no se puede descargar el resultado.
batch_not_editable
El estado actual de la traducción no permite realizar el cambio de mantenimiento solicitado.
Códigos de archivos y formatos
unsupported_format
La extensión del archivo no es compatible con AI Glot. Consulta Archivos y formatos para ver todos los formatos y sus extensiones.
file_too_large
El archivo supera el límite de tamaño de su formato. Los límites dependen del formato y no son globales (60 MB para CSV y 4 MB para un catálogo PO), por lo que un tamaño válido para una extensión puede rechazarse para otra.
file_fetch_failed
No se ha podido obtener file_url. La URL debe usar HTTPS y apuntar al destino final. No se siguen las redirecciones, por lo que un enlace acortado o uno firmado que después redirige dará este error.
file_retention_expired
Ha vencido el periodo de conservación del archivo subido y ya no está almacenado. Vuelve a crear la traducción a partir del archivo de origen.
file_expired
El archivo asociado a esta traducción ya no está disponible, por lo que no se puede continuar con la operación.
result_too_large
La traducción terminada supera el tamaño máximo de respuesta. Divide el archivo de origen y tradúcelo por partes.
Códigos de planes y aprobaciones
plan_invalid
No se ha podido convertir la instrucción o el refinamiento en un plan utilizable. Exprésalo de otra forma: suele ser más fiable indicar los campos o columnas que hay que traducir que describirlos.
no_plan_yet
Se ha intentado aprobar antes de que existiera un plan. Llama primero a POST /v1/batches/{batch_id}/plan. Esta comprobación evita que una integración cobre al espacio de trabajo por una traducción que nadie ha descrito.
batch_not_awaiting_approval
La traducción no se encuentra en un estado que permita aprobarla; normalmente, ya está en curso o ha terminado. Consulta GET /v1/batches/{batch_id} en lugar de volver a aprobarla.
insufficient_credits
El saldo del espacio de trabajo no cubre el coste calculado del plan. No se reserva ningún crédito, por lo que se podrá aprobar la traducción cuando se añadan créditos.
Códigos de idiomas y glosarios
language_not_supported
La etiqueta no está incluida en el catálogo de idiomas compatibles. Consulta GET /v1/languages.
invalid_language_pair
El identificador de la combinación de idiomas no se puede dividir en dos etiquetas BCP 47 compatibles.
glossary_term_limit_reached
El número total de términos superaría el límite del plan del espacio de trabajo. La actualización es atómica: no se ha cambiado nada.
glossary_limit_reached
El espacio de trabajo ha alcanzado el número máximo de glosarios permitido por el plan actual.
invalid_glossary_terms
Una o varias entradas del glosario están vacías, incompletas o no son válidas por otro motivo.
Códigos de servicio
rate_limited
La credencial ha superado el límite de solicitudes de un periodo. Espera a Retry-After y vuelve a intentarlo con una variación aleatoria.
internal_error
AI Glot ha fallado de forma inesperada. Reintenta con esperas progresivas y conserva el request_id.
service_unavailable
Un servicio necesario no está disponible temporalmente. Reintenta con esperas progresivas.