Errores
Gestiona los errores de la API de AI Glot con códigos de error estables, identificadores de solicitud, indicaciones para reintentar y explicaciones con enlaces directos para cada error documentado.
Todos los errores de la API utilizan el mismo formato. Usa error.code para decidir cómo actuar, nunca el mensaje legible para las personas.
{
"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 | Autenticado, pero sin permiso | Concede el ámbito o la función necesarios |
| 404 | Recurso inexistente o ajeno a 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 | Límite de solicitudes alcanzado | Espera el tiempo indicado en Retry-After |
| 500/503 | AI Glot ha fallado o no está disponible temporalmente | Vuelve a intentarlo con esperas progresivas |
Códigos de autenticación y permisos
authentication_required
No se ha enviado ninguna credencial bearer. Añade la cabecera 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 una clave de sustitución.
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 esta no cumple el contrato del endpoint.
unknown_field
No se reconoce una propiedad del cuerpo JSON. Corrige la errata en lugar de eliminar la validación. Los parámetros de consulta desconocidos no generan este error: se ignoran, por lo que un filtro mal escrito devuelve un 200 sin filtrar los resultados.
invalid_parameter
Un parámetro tiene un tipo, intervalo o formato incorrecto.
invalid_cursor
El cursor de paginación no es válido. Reutiliza next_cursor exactamente tal como se devuelve.
request_too_large
El cuerpo de la solicitud supera el límite máximo del endpoint.
Códigos de recursos y estado
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 esta 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 el cambio de mantenimiento solicitado.
idempotency_key_reused
La Idempotency-Key ya se usó para otra solicitud (otro archivo, nombre o instrucción). Envía la misma solicitud para repetirla, o una clave nueva para un trabajo nuevo. Consulta Crear una traducción.
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 son específicos de cada formato, no globales (60 MB para CSV y 4 MB para un catálogo PO), por lo que un tamaño aceptado para una extensión puede rechazarse para otra.
file_fetch_failed
No se ha podido recuperar file_url. La URL debe usar HTTPS y apuntar al destino final: no se siguen redirecciones, por lo que un enlace acortado o que redirige después de firmarse provocará 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 que se puede devolver. Divide el archivo de origen y tradúcelo por partes.
Códigos de plan y aprobación
plan_invalid
No se ha podido convertir la instrucción o el refinamiento en un plan utilizable. No se ha cobrado nada. Si se conoce la causa, el mensaje la indica: ningún contenido del archivo coincide con la instrucción, esta pide escribir en un lugar que el archivo no admite o no se ha podido generar el plan en este intento (envía de nuevo la misma instrucción). Si no, reformúlala: suele ser más fiable indicar los campos o columnas que hay que traducir.
plan_changed
El valor enviado en expected_plan_revision no coincide con el plan actual que se puede revisar, o no se puede verificar esa revisión. Esta aprobación no ha iniciado ningún trabajo nuevo. Vuelve a consultar el lote, revisa su alcance, las exclusiones y el coste calculado, y decide si lo apruebas con la nueva revisión. No vuelvas a enviar la aprobación anterior sin comprobarlo.
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 a un espacio de trabajo por una traducción que nadie ha descrito.
batch_not_awaiting_approval
La traducción no está en un estado que permita aprobarla; normalmente ya se está procesando 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 (HTTP 402). No se ha reservado nada, por lo que se podrá aprobar la traducción cuando se añadan créditos.
El error incluye un objeto payment, tanto en la API REST como en la herramienta MCP approve_translation:
"payment": {
"credits_needed": 30000,
"credit_balance": 5000,
"credits_missing": 25000,
"credits_to_buy": 25000,
"price_eur": 25,
"payment_url": "https://app.ai-glot.com/w/<workspace_id>/new?continue=<batch_id>&pay=1",
"plans": [
{ "plan": "Starter", "eur_per_month": 42, "credits_per_month": 100000 },
{ "plan": "Pro", "eur_per_month": 199, "credits_per_month": 1000000 }
]
}credits_to_buy es la compra mínima que cubre la diferencia (se aplica el importe mínimo de compra). payment_url abre esta traducción en AI Glot con la ventana de compra ya abierta: muestra el importe exacto, los paquetes de créditos y los planes, así como la muestra gratuita si el espacio de trabajo cumple los requisitos. El enlace solo funciona para un miembro del espacio de trabajo que haya iniciado sesión, por lo que se puede mostrar sin riesgos. plans muestra los planes mensuales, que ofrecen un coste por crédito menor a quienes traducen con regularidad; aparecen en la misma página, debajo de la compra puntual.
Un agente debe consultar a su usuario antes de ofrecerle el enlace y nunca pagar en su nombre. Una vez realizado el pago, debe comprobar el saldo con GET /v1/account y volver a aprobar cuando el usuario lo confirme. El usuario también puede iniciar la traducción desde esa página.
Códigos de idioma y glosario
language_not_supported
La etiqueta no forma parte del catálogo de idiomas admitidos. Consulta GET /v1/languages.
invalid_language_pair
El identificador de la combinación de idiomas no se puede dividir en dos etiquetas BCP 47 admitidas.
glossary_term_limit_reached
El número de términos resultante 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 más entradas del glosario están vacías, incompletas o no son válidas por algún otro motivo.
Códigos de servicio
rate_limited
La credencial ha superado el límite de solicitudes en un intervalo. Espera el tiempo indicado en Retry-After y vuelve a intentarlo con una variación aleatoria.
internal_error
AI Glot ha fallado de forma inesperada. Vuelve a intentarlo con esperas progresivas y conserva request_id.
service_unavailable
Un servicio necesario no está disponible temporalmente. Vuelve a intentarlo con esperas progresivas.