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 utilizan la misma estructura de respuesta. Aplica la lógica en función de error.code, nunca del mensaje descriptivo.
{
"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 con formato incorrecto o campo desconocido | Corrige la solicitud |
| 401 | Credencial ausente, no válida, caducada o revocada | Sustitúyela o renuévala |
| 403 | Autenticado pero sin permisos | Concede el ámbito o la funcionalidad requeridos |
| 404 | Recurso no encontrado o fuera de este espacio de trabajo | Comprueba el ID y el espacio de trabajo |
| 409 | El estado actual entra en conflicto con la solicitud | Lee el recurso y decide a continuación |
| 413 | Cuerpo de la solicitud demasiado grande | Envía un cuerpo de menor tamaño |
| 422 | Valor con formato correcto pero no válido | Corrige el valor indicado |
| 429 | Límite de frecuencia superado | Espera al valor de Retry-After |
| 500/503 | Error en AI Glot o servicio no disponible temporalmente | Reintenta con retroceso exponencial |
Códigos de autenticación y permisos
authentication_required
No se ha enviado ninguna credencial de tipo Bearer. Añade la cabecera Authorization.
invalid_api_key
La clave tiene un formato incorrecto o es desconocida. Comprueba que se haya copiado el valor aig_live_… completo.
api_key_expired
La clave ha alcanzado su fecha de expiración configurada. Genera o utiliza otra de sustitución.
api_key_revoked
Un administrador ha revocado o rotado esta clave. Actualiza la integración con una credencial activa.
insufficient_scope
La credencial se ha autenticado correctamente, pero carece del ámbito necesario para esta operación.
feature_not_available
El plan del espacio de trabajo o la versión actual de la plataforma no incluyen 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 procesar la solicitud o no coincide con el contrato del endpoint.
unknown_field
No se reconoce una propiedad del cuerpo JSON. Corrige el nombre del campo en lugar de eliminar la validación. Los parámetros de consulta (query parameters) no reconocidos nunca generan este error; simplemente se ignoran, por lo que un filtro mal escrito devolverá 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. Reutiliza next_cursor exactamente tal como se devolvió.
request_too_large
El cuerpo de la solicitud supera el límite estricto del endpoint.
Códigos de recurso y estado
batch_not_found
Ninguna traducción visible coincide con ese ID. Los recursos de otro espacio de trabajo devuelven este mismo error de forma intencionada.
glossary_not_found
No existe ningún 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ízalo en lugar de crear uno nuevo.
result_not_ready
La traducción aún no ha finalizado, por lo que todavía no se puede descargar ningún resultado.
batch_not_editable
El estado actual de la traducción no permite realizar el cambio de mantenimiento solicitado.
Códigos de archivo y formato
unsupported_format
La extensión del archivo no está admitida por AI Glot. Consulta Archivos y formatos para conocer las doce familias y sus extensiones.
file_too_large
El archivo supera el límite establecido para su formato. Los límites son por formato y no globales (60 MB para CSV, 4 MB para un catálogo PO), por lo que un tamaño válido para una extensión puede ser rechazado en otra.
file_fetch_failed
No se ha podido obtener file_url. La URL debe ser HTTPS y apuntar al destino final: no se siguen redirecciones, por lo que un enlace acortado o firmado que redirija fallará aquí.
file_retention_expired
El archivo subido ha superado su periodo de retención y ya no está almacenado. Vuelve a crear la traducción a partir del archivo de origen.
file_expired
El archivo que respalda esta traducción ya no existe, por lo que no se puede continuar con la operación.
result_too_large
La traducción completada supera el tamaño máximo permitido para su devolución. 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 ajuste en un plan utilizable. Reformúlalo: especificar los nombres de los campos o columnas a traducir es más fiable que describirlos.
no_plan_yet
Se ha intentado aprobar la traducción antes de que existiera un plan. Llama primero a POST /v1/batches/{batch_id}/plan; este control evita que una integración cobre a un espacio de trabajo por una traducción que nadie ha definido.
batch_not_awaiting_approval
La traducción no se encuentra en un estado que admita aprobación; por lo general, ya está en ejecución o ha finalizado. Consulta GET /v1/batches/{batch_id} mediante sondeo en lugar de intentar aprobarla de nuevo.
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 la traducción seguirá disponible para su aprobación una vez que se añadan créditos.
Códigos de idioma y glosario
language_not_supported
La etiqueta no está incluida en el catálogo admitido. Consulta GET /v1/languages.
invalid_language_pair
El identificador del par de idiomas no se puede dividir en dos etiquetas BCP 47 admitidas.
glossary_term_limit_reached
El número resultante de términos superaría el límite permitido por el plan del espacio de trabajo. La actualización es atómica; no se ha aplicado ningún cambio.
glossary_limit_reached
El espacio de trabajo ha alcanzado el límite de glosarios permitidos para su plan actual.
invalid_glossary_terms
Una o varias entradas del glosario están vacías, incompletas o no son válidas.
Códigos de servicio
rate_limited
La credencial ha superado la ventana de límite de frecuencia. Espera al valor de Retry-After y reintenta con una variación aleatoria (jitter).
internal_error
AI Glot ha sufrido un error inesperado. Reintenta con retroceso exponencial y conserva el request_id.
service_unavailable
Uno de los servicios requeridos no está disponible temporalmente. Reintenta con retroceso exponencial.