Errores Comunes de API

Este artículo le ayudará a comprender los errores de API más comunes que pueden encontrarse al utilizar la plataforma en la nube de EKB. Encontrará detalles sobre los diversos códigos de estado HTTP y códigos de error específicos, proporcionándole los pasos esenciales de solución de problemas para resolver estas dificultades de manera efectiva. Al comprender el formato de respuesta de error y los errores comunes asociados con el uso de la API, estará mejor preparado para manejar errores y mejorar su experiencia de desarrollo.

Formato de Respuesta de Error

Todos los errores de API siguen un formato consistente:

{
  "status_code": 400,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  },
  "detail": "Additional error details (optional)"
}

Algunos errores también pueden incluir:

• error_id: Identificador único para rastrear el error
• invalid_fields: Lista de campos que fallaron la validación (para errores de validación)

Códigos de Estado HTTP

400 Solicitud Incorrecta

Errores del lado del cliente debido a entradas no válidas o solicitudes mal formateadas.

VALIDATION_ERROR

Código de Error: VALIDATION_ERROR Código de Estado: 400

Descripción: Falló la validación de la solicitud. Uno o más campos en la solicitud son inválidos.

Causas Comunes:

• Campos obligatorios faltantes
• Formato de campo inválido (por ejemplo, correo electrónico inválido, formato de fecha)
• Valores de campo fuera del rango permitido
• Tipos de datos inválidos

Ejemplo de Respuesta:

{
  "status_code": 400,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "invalid_fields": ["email", "project_id"]
  }
}

Solución de Problemas:

1. Revise la matriz invalid_fields para identificar los campos problemáticos
2. Consulte los requisitos de campos en la documentación de la API
3. Verifique que los tipos de datos coincidan con los formatos esperados
4. Asegúrese de proporcionar todos los campos obligatorios

INVALID_API_KEY

Código de Error: INVALID_API_KEY
Código de Estado: 400

Descripción: La clave de API proporcionada es inválida o está mal formateada.

Solución de Problemas:

1. Verifique que la clave de API esté copiada correctamente (sin espacios adicionales)
2. Compruebe si la clave de API está activa en Mi Cuenta > Claves de API
3. Asegúrese de estar utilizando la clave de API correcta para su entorno
4. Regenere la clave de API si es necesario

INVALID_CREDENTIALS

Código de Error: INVALID_CREDENTIALS
Código de Estado: 400

Descripción: Las credenciales de autenticación son inválidas.

Solución de Problemas:

1. Verifique que el correo electrónico y la contraseña sean correctos
2. Compruebe si la cuenta está bloqueada o deshabilitada
3. Intente restablecer su contraseña
4. Asegúrese de estar utilizando el método de autenticación correcto

INVALID_OR_EXPIRED_JWT_TOKEN

Código de Error: INVALID_OR_EXPIRED_JWT_TOKEN
Código de Estado: 400

Descripción: El token JWT es inválido, ha expirado o está mal formateado.

Solución de Problemas:

1. Actualice su token de autenticación
2. Cierre sesión y vuelva a iniciar sesión
3. Compruebe el tiempo de expiración del token
4. Verifique que el token se envíe en el formato de encabezado correcto

401 No Autorizado

Se requiere autenticación o la autenticación falló.

AUTHENTICATION

Código de Error: AUTHENTICATION
Código de Estado: 401

Descripción: Se requiere autenticación para acceder a este recurso.

Solución de Problemas:

1. Asegúrese de haber iniciado sesión
2. Compruebe si su sesión ha expirado
3. Verifique que los encabezados de autenticación estén incluidos en la solicitud
4. Vuelva a autenticarse si es necesario

INVALID_BEARER_TOKEN

Código de Error: INVALID_BEARER_TOKEN
Código de Estado: 401

Descripción: El token Bearer proporcionado es inválido.

Solución de Problemas:

1. Verifique el formato del token: Bearer <token>
2. Compruebe si el token ha expirado
3. Regenere el token de autenticación
4. Asegúrese de que el token no haya sido revocado

EMAIL_IS_NOT_VERIFIED

Código de Error: EMAIL_IS_NOT_VERIFIED
Código de Estado: 401

Descripción: La dirección de correo electrónico no ha sido verificada.

Solución de Problemas:

1. Revise su correo electrónico en busca del enlace de verificación
2. Solicite un nuevo correo de verificación
3. Verifique que la dirección de correo electrónico sea correcta
4. Revise la carpeta de correo no deseado o spam

403 Prohibido

Acceso denegado debido a permisos insuficientes.

AUTHORIZATION

Código de Error: AUTHORIZATION
Código de Estado: 403

Descripción: No tiene permisos para realizar esta acción.

Solución de Problemas:

1. Verifique que tenga el rol/permisos requeridos
2. Compruebe si es miembro del proyecto/equipo
3. Contacte al administrador del proyecto/equipo para otorgar acceso
4. Asegúrese de estar accediendo al recurso correcto

PERMISSION_DENIED

Código de Error: PERMISSION_DENIED
Código de Estado: 403

Descripción: Permiso denegado para la operación solicitada.

Solución de Problemas:

1. Revise su rol de usuario y permisos
2. Compruebe la configuración de acceso del proyecto/equipo
3. Verifique la propiedad del recurso
4. Contacte al administrador para solicitar acceso

DOMAIN_NOT_ALLOWED

Código de Error: DOMAIN_NOT_ALLOWED
Código de Estado: 403

Descripción: Su dominio de correo electrónico no está permitido para esta operación.

Solución de Problemas:

1. Verifique que su dominio de correo electrónico esté en la lista de permitidos
2. Contacte al administrador para agregar su dominio
3. Utilice una dirección de correo electrónico permitida

404 No Encontrado

El recurso solicitado no existe.

ENTITY_NOT_FOUND

Código de Error: ENTITY_NOT_FOUND
Código de Estado: 404

Descripción: No se encontró el recurso solicitado.

Escenarios Comunes:

• Proyecto no encontrado
• Agente no encontrado
• Documento no encontrado
• Usuario no encontrado

Solución de Problemas:

1. Verifique que el ID del recurso sea correcto
2. Compruebe si el recurso fue eliminado
3. Asegúrese de tener acceso al recurso
4. Verifique que esté utilizando el proyecto/espacio de trabajo correcto

FILE_NOT_FOUND

Código de Error: FILE_NOT_FOUND
Código de Estado: 404

Descripción: El archivo solicitado no existe.

Solución de Problemas:

1. Verifique que la ruta o el ID del archivo sea correcto
2. Compruebe si el archivo fue eliminado
3. Asegúrese de que el archivo esté en la ubicación esperada
4. Verifique los permisos del archivo

FLOW_NOT_FOUND

Código de Error: FLOW_NOT_FOUND
Código de Estado: 404

Descripción: No se encontró el flujo/workflow solicitado.

Solución de Problemas:

1. Verifique que el ID del flujo sea correcto
2. Compruebe si el flujo fue eliminado
3. Asegúrese de tener acceso al flujo
4. Verifique que el flujo exista en el proyecto actual

CONFIG_NOT_FOUND

Código de Error: CONFIG_NOT_FOUND
Código de Estado: 404

Descripción: No se encontró la configuración requerida.

Solución de Problemas:

1. Verifique que la configuración exista
2. Compruebe la configuración en los ajustes
3. Asegúrese de que los servicios requeridos estén configurados
4. Revise la documentación de configuración

500 Error Interno del Servidor

Errores del lado del servidor que requieren investigación.

ENGINE_OPERATION_FAILURE

Código de Error: ENGINE_OPERATION_FAILURE
Código de Estado: 500

Descripción: Falló una operación interna del motor.

Solución de Problemas:

1. Reintente la solicitud después de unos momentos
2. Compruebe el estado del sistema en status.getodin.ai
3. Si persiste, contacte al soporte con los detalles del error
4. Proporcione el ID del error si está disponible

EXTERNAL_SERVICE

Código de Error: EXTERNAL_SERVICE
Código de Estado: 500

Descripción: Un servicio externo requerido para esta operación falló.

Escenarios Comunes:

• Fallo en la API del proveedor LLM
• Fallo en la integración de terceros (Google Drive, Slack, etc.)
• Tiempo de espera agotado en API externa

Solución de Problemas:

1. Compruebe el estado del servicio externo
2. Verifique las claves de API/credenciales para servicios externos
3. Reintente la solicitud
4. Compruebe la configuración de la integración
5. Contacte al soporte si el problema persiste

INFRASTRUCTURE

Código de Error: INFRASTRUCTURE
Código de Estado: 500

Descripción: Error de infraestructura (base de datos, almacenamiento, etc.).

Solución de Problemas:

1. Reintente la solicitud
2. Compruebe el estado del sistema
3. Si persiste, contacte al soporte
4. Proporcione los detalles del error y la marca de tiempo

OPEN_AI_FAILED

Código de Error: OPEN_AI_FAILED
Código de Estado: 500

Descripción: Falló la llamada a la API de OpenAI.

Solución de Problemas:

1. Compruebe el estado del servicio de OpenAI
2. Verifique que la clave de API sea válida y tenga créditos
3. Compruebe los límites de velocidad
4. Reintente con retroceso exponencial
5. Verifique la disponibilidad del modelo

503 Servicio No Disponible

Servicio temporalmente no disponible.

EXECUTION_TIMEOUT

Código de Error: EXECUTION_TIMEOUT
Código de Estado: 503

Descripción: La operación excedió el tiempo de espera.

Solución de Problemas:

1. Reintente la solicitud
2. Simplifique la operación si es posible
3. Compruebe si el sistema está bajo alta carga
4. Divida las operaciones grandes en operaciones más pequeñas
5. Contacte al soporte si el tiempo de espera persiste

Errores de Lógica de Negocio

QUOTA_EXCEEDED

Código de Error: QUOTA_EXCEEDED
Código de Estado: 400 o 429

Descripción: Ha excedido el límite de su cuota.

Solución de Problemas:

1. Compruebe su uso actual en Mi Cuenta > Panel de Control
2. Revise los límites de su suscripción
3. Actualice su plan si es necesario
4. Espere al período de restablecimiento de cuota
5. Contacte a ventas para aumentar la cuota

FEATURE_DISABLED

Código de Error: FEATURE_DISABLED
Código de Estado: 400

Descripción: Esta función está deshabilitada para su cuenta.

Solución de Problemas:

1. Compruebe su plan de suscripción
2. Verifique la disponibilidad de la función
3. Actualice su plan si la función requiere un nivel superior
4. Contacte al soporte para acceder a la función

FLOW_IN_USE

Código de Error: FLOW_IN_USE
Código de Estado: 400

Descripción: El workflow está actualmente en uso y no puede ser modificado.

Solución de Problemas:

1. Espere a que finalicen las ejecuciones activas
2. Cancele las ejecuciones activas del workflow
3. Compruebe el estado de ejecución del workflow
4. Reintente después de que finalicen las ejecuciones

EXISTING_USER

Código de Error: EXISTING_USER
Código de Estado: 400

Descripción: Ya existe un usuario con este correo electrónico.

Solución de Problemas:

1. Intente iniciar sesión en lugar de registrarse
2. Utilice el restablecimiento de contraseña si olvidó sus credenciales
3. Utilice una dirección de correo electrónico diferente
4. Contacte al soporte si necesita recuperación de cuenta

Errores Específicos de Integración

INVALID_APP_CONNECTION

Código de Error: INVALID_APP_CONNECTION
Código de Estado: 400

Descripción: Conexión de aplicación inválida o expirada (integración OAuth).

Solución de Problemas:

1. Vuelva a autenticar la integración
2. Compruebe la expiración del token OAuth
3. Verifique las credenciales de la integración
4. Vuelva a conectar la integración en los ajustes

INVALID_SAML_RESPONSE

Código de Error: INVALID_SAML_RESPONSE
Código de Estado: 400

Descripción: Respuesta SAML inválida del proveedor SSO.

Solución de Problemas:

1. Verifique la configuración de SSO
2. Compruebe la URL de metadatos SAML
3. Asegúrese de que el proveedor SSO sea accesible
4. Contacte al soporte para revisión de la configuración de SSO

RATE_LIMITED

Código de Error: RATE_LIMITED o ratelimited
Código de Estado: 429

Descripción: Se excedió el límite de velocidad de la API.

Solución de Problemas:

1. Espere a que se restablezca la ventana de límite de velocidad
2. Implemente retroceso exponencial
3. Reduzca la frecuencia de solicitudes
4. Compruebe los encabezados de límite de velocidad en la respuesta
5. Actualice su plan para obtener límites de velocidad más altos

Obtener Ayuda

Si encuentra un error que no se indica aquí o necesita asistencia:

1. Compruebe los Detalles del Error: Anote el código de error, el mensaje y el error_id
2. Compruebe el Estado del Sistema: Visite status.getodin.ai para problemas conocidos
3. Revise la Documentación: Consulte la documentación relevante de la API
4. Contacte al Soporte: Envíe un correo electrónico a Soporte con:
   • Código y mensaje de error
   • ID del error (si está disponible)
   • Pasos para reproducir
   • Detalles de solicitud/respuesta (sanitizados)
   • Marca de tiempo del error