AI Glot websiteOpen AI Glot
REST APIErrores

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.

Example 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

EstadoSignificadoQué hacer
400Solicitud mal formada o campo desconocidoCorrige la solicitud
401Credencial ausente, no válida, caducada o revocadaSustitúyela o renuévala
403Autenticado, pero sin permisoConcede el ámbito o la función necesarios
404Recurso inexistente o ajeno a este espacio de trabajoComprueba el ID y el espacio de trabajo
409El estado actual entra en conflicto con la solicitudConsulta el recurso y decide cómo proceder
413El cuerpo de la solicitud es demasiado grandeEnvía un cuerpo más pequeño
422Valor bien formado, pero no válidoCorrige el valor indicado
429Límite de solicitudes alcanzadoEspera el tiempo indicado en Retry-After
500/503AI Glot ha fallado o no está disponible temporalmenteVuelve 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:

JSON
"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.

Use these docs with your AI tools

An AI agent can read this documentation directly. You do not need an account or an API key. Everything here is public and read-only.

Query these docs via MCP

Recommended

Add this server to Claude, Claude Code, Cursor, Mistral, or any tool that supports MCP. Your agent can then search AI Glot Docs documentation and read it in full, instead of answering from memory.

https://ai-glot.com/docs/mcp
  • searchFind the passages that answer a question.
  • fetchRead one page in full, as Markdown.
  • list_pagesSee every page in this documentation.

Query these docs over HTTP

The same tools also work as plain web requests. Use this for scripts, or for any tool that does not support MCP. There is one endpoint per tool. Arguments go in the query string, and the answer comes back as JSON.

https://ai-glot.com/docs/api/docs/search?query=custom+domain

Read the OpenAPI description. It is built from the same definitions as the tools, so it always matches what the endpoints do.

Read these docs as Markdown

Add .md to any page URL to get its Markdown source. You can also send the headerAccept: text/markdown to the page URL itself.

To read the whole documentation in one file, open llms-full.txt. For a short index of every page, open llms.txt.