Saltar al contenido

Solución de problemas de APIs y API Manager

Esta guía cubre errores y problemas comunes al configurar, publicar y usar APIs en Jitterbit API Manager. Comienza con los pasos de diagnóstico a continuación para recopilar información, luego encuentra tu problema específico en la sección relevante.

Para una referencia unificada que cubra problemas de integración, automatización, gestión de APIs, EDI y desarrollo de aplicaciones en un solo lugar, consulta la guía de solución de problemas de Harmony.

Todas las entradas de solución de problemas en esta página

Pasos de diagnóstico

Estos pasos se aplican a la mayoría de los problemas de API Manager y son el punto de partida recomendado.

Revisar los registros de la API

Revisa los registros de la API para ver errores de solicitud y respuesta relacionados con la API afectada. De forma predeterminada, los registros muestran metadatos como códigos de estado, mensajes de error y marcas de tiempo, lo que puede ayudar a reducir la causa.

Para capturar también las cargas útiles completas de solicitud y respuesta, usa el modo de depuración, la mejor opción para la solución de problemas activa: captura datos de solicitud y respuesta junto con un registro detallado a nivel de actividad, y se desactiva automáticamente en la fecha que establezca.

  1. En la pestaña Configuración de la configuración de la API, activa Habilitar modo de depuración hasta y establece una fecha para mantenerlo activo. Consulta la referencia de configuración para API personalizadas, servicios OData o API proxy.
  2. Reproduce la solicitud y luego revisa las cargas útiles en los registros de la API.

Nota

Para registrar cargas útiles de forma continua en lugar de hacerlo durante una ventana de solución de problemas fija, usa Registro detallado o Mostrar cargas útiles de solicitud y respuesta en registros para servicios personalizados y OData.

Revisar el estado del sistema Jitterbit

Si un problema parece afectar todas las API o la interfaz de API Manager en sí en lugar de una sola API, consulta la página de estado del sistema Jitterbit y la página de problemas conocidos antes de investigar más.

Fallos de autenticación y seguridad

OAuth de Microsoft Entra ID: El nombre del perfil de seguridad no puede contener espacios

  • Síntoma: Las llamadas a la API que utilizan un perfil de seguridad OAuth 2.0 de tres pasos de Microsoft Entra ID (Azure AD) fallan con un error de Microsoft que indica una falta de coincidencia de URL de respuesta:

    The reply URL specified in the request does not match the reply URLs configured for the application.

  • Posible causa: El nombre del perfil de seguridad contiene espacios. Los espacios en el nombre del perfil hacen que el URI de redirección de OAuth se construya incorrectamente, lo que no coincide con ninguna de las URL de respuesta registradas en el registro de la aplicación de Azure.

  • Resolución:
    1. Abre el perfil de seguridad en API Manager y cámbialo de nombre para eliminar los espacios (por ejemplo, cambia My Profile a MyProfile o my-profile).
    2. En el registro de la aplicación de Azure, verifica que las URL de respuesta registradas allí coincidan con el URI de redirección que API Manager genera para el perfil renombrado.

OAuth de dos pasos de Microsoft Entra ID: error OAUTH_INVALID_TOKEN_CODE

  • Síntoma: Las llamadas a la API protegidas por un perfil de seguridad OAuth 2.0 de dos pasos de Microsoft Entra ID fallan con:

    Failed to validate authentication token - HttpErrorResponse: OAUTH_INVALID_TOKEN_CODE

  • Posible causa: La notificación aud en el JWT emitido por Entra ID no coincide con la audiencia configurada en el perfil de seguridad de API Manager. Esto generalmente indica que el URI de ID de aplicación en el registro de aplicación de Azure está mal configurado, o el alcance de OAuth que solicita el cliente no coincide con el URI registrado.

  • Resolución:
    1. En Azure Portal, abre el registro de aplicación asignado a este perfil de seguridad y ve a Exponer una API.
    2. Confirma que el URI de ID de aplicación esté configurado en un URI válido con el formato api://<Application (client) ID>.
    3. En el perfil de seguridad, confirma que el Alcance de OAuth esté configurado en api://<Application (client) ID>/.default.
    4. Actualiza la aplicación cliente para solicitar un token usando este alcance exacto.
    5. Si la validación sigue fallando después de que la audiencia y el alcance sean correctos, abre el manifiesto del registro de aplicación y confirma que requestedAccessTokenVersion esté configurado en 2. Un valor faltante o diferente también puede causar que la validación del token falle.

Azure AD Graph API ha sido retirado

  • Síntoma: Las llamadas a API que anteriormente funcionaban con un perfil de seguridad de Microsoft Entra ID (Azure AD) fallan con errores de autenticación.
  • Posible causa: El registro de aplicación del perfil de seguridad sigue configurado para usar Azure AD Graph API, que Microsoft retiró el 30 de junio de 2025. Los registros de aplicación que no se migraron a Microsoft Graph fallan al realizar solicitudes.
  • Resolución:
    1. En Azure Portal, migra el registro de aplicación a Microsoft Graph.
    2. Después de migrar, actualiza el manifiesto de la aplicación siguiendo los pasos de permisos de API en la configuración del perfil de seguridad OAuth de 2 patas de Microsoft Entra ID.

Proveedor de identidad de Google o Salesforce: OAuth de 2 patas no es compatible

  • Síntoma: Un perfil de seguridad de API configurado con Google o Salesforce como proveedor de identidad OAuth 2.0 falla cuando se configura para OAuth de 2 patas.
  • Posible causa: Los perfiles de seguridad de API de OAuth 2.0 de Google y Salesforce no admiten OAuth de 2 patas.
  • Resolución: Usa un perfil de seguridad OAuth 2.0 de 3 patas para las API que se autentican con Google o Salesforce como proveedor de identidad.

Microsoft Copilot Studio: Autenticación básica no compatible

  • Síntoma: La conexión de una API personalizada de Jitterbit a Microsoft Copilot Studio (como herramienta de API REST) falla cuando el perfil de seguridad de la API usa autenticación básica.
  • Posible causa: Microsoft Copilot Studio no admite autenticación básica. Una API personalizada de Jitterbit cuyo perfil de seguridad usa autenticación básica no puede ser llamada desde Copilot Studio.
  • Resolución:
    1. En API Manager, abre el perfil de seguridad asignado a la API.
    2. Cambia el tipo de autenticación a Clave de API u OAuth 2.0, o elimina el perfil de seguridad de la API si el endpoint no requiere autenticación.
    3. Republica la API y luego reconéctala en Microsoft Copilot Studio. Consulta Conectar un agente de IA de Jitterbit a Microsoft Copilot Studio.

Botón "New API" no visible a pesar de tener el rol de organización correcto

  • Síntoma: El botón New API no aparece en API Manager para un usuario que tiene un rol a nivel de organización pero no es administrador de la organización. Otorgar al usuario el permiso Admin a nivel de organización hace que el botón aparezca, pero también expone todos los entornos al usuario.
  • Causa posible: Un rol a nivel de organización por sí solo no es suficiente para crear APIs. El rol también debe tener acceso de Write otorgado a nivel de entorno para el entorno específico donde necesita crear APIs.
  • Resolución:
    1. En la Consola de Administración, ve a Environments y abre el entorno donde el usuario necesita crear APIs.
    2. Para el rol del usuario en ese entorno, confirma que el acceso de Write esté habilitado. Si no es así, habilítalo y guarda.
    3. El botón New API ahora debe ser visible para ese entorno.
  • Síntoma: Una API con dos o más perfiles de seguridad de autenticación Basic asignados muestra nombres de usuario inesperados en los registros de API, incluyendo nombres de usuario que no pertenecen a ninguno de los perfiles. Algunas solicitudes fallan con un error 401 Unauthorized.
  • Causa posible: El navegador o cliente de API (como Postman) ha almacenado en caché las credenciales de autenticación básica de una sesión anterior como una cookie. Cuando se llama a la API nuevamente, el cliente envía la cookie almacenada en caché primero. Si las credenciales en caché no coinciden con ninguno de los perfiles de seguridad configurados, la solicitud se rechaza y el nombre de usuario inesperado aparece en los registros antes de que la autenticación tenga éxito con las credenciales correctas.

  • Resolución:

    1. Borra las cookies y el caché del navegador, o cambia a una ventana de navegación incógnita o privada, antes de volver a probar la API.
    2. Confirma que el comportamiento no está presente cuando se realiza una solicitud nueva sin cookies de sesión anterior. Si el error desaparece, el problema es el almacenamiento en caché de credenciales del lado del cliente y no un problema de configuración.

    Ten en cuenta que cualquier cliente HTTP que almacene cookies (incluyendo herramientas basadas en navegador y utilidades de prueba de API) puede exhibir el mismo comportamiento.

401 Unauthorized con una lista de IP permitidas válida (caché obsoleto)

  • Síntoma: Las llamadas a la API devuelven 401 Unauthorized aunque la IP del cliente esté correctamente listada en los grupos de IP de confianza del perfil de seguridad.
  • Causa posible: Un caché obsoleto de entradas de rango de IP heredadas en el perfil de seguridad está anulando los grupos de IP de confianza activos.
  • Resolución: Migra el perfil de seguridad de rangos de IP heredados al modelo de Trusted IP Groups, el mecanismo de lista de permitidos actual: define las IPs como un grupo de IP de confianza y asígnalo al perfil. Deshabilitar la configuración Trust requests only from the following IP ranges en un perfil que aún usa rangos de IP heredados elimina permanentemente esos rangos (un mensaje de confirmación advierte sobre esto), así que migra las IPs a un grupo de IP de confianza en lugar de desactivar la configuración para limpiar el caché.

Publicación e implementación de API

No se puede publicar una API: Se alcanzó el límite de API de suscripción

  • Síntoma: La creación o publicación de una API falla con un error como:

    You have reached Maximum no of API Service configured for your Jitterbit organization

  • Causa: La organización ha alcanzado el número máximo de URLs de API publicadas permitidas por su suscripción. Cada API personalizada publicada, servicio OData o API proxy (y cada uno de sus clones publicados) utiliza una URL de API; las APIs en borrador no cuentan.

  • Resolución: En la página APIs de API Manager, verifica los conteos de Custom API URLs used y Proxy API URLs used, mostrados en la parte superior de la página, contra los totales permitidos por tu suscripción. Despublica o elimina las APIs que ya no necesites para liberar URLs de API (las APIs en borrador no cuentan contra el límite). Para aumentar el límite, contacta a tu Customer Success Manager.

La API publicada devuelve 404 Not Found

  • Síntoma: Llamar a una API publicada devuelve un error 404.
  • Posibles causas:
    • El límite de Hits por minuto en el perfil de seguridad asignado está configurado en cero, bloqueando todas las solicitudes. Un cambio en el nivel de suscripción de la organización puede restablecer este límite, por lo que una API que funcionaba anteriormente puede comenzar a devolver 404s.
    • La configuración, URL base o configuración de visibilidad de la API son incorrectas.
    • Una puerta de enlace de API privada no reconoce la API después de la implementación.
    • La API no se ha publicado completamente o sus metadatos están incompletos.
  • Resolución:
    • Abre el perfil de seguridad asignado a la API y confirma que el valor de Hits por minuto está configurado en un número distinto de cero. Si el límite se restableció recientemente (por ejemplo, después de un cambio de suscripción), restáuralo al valor deseado.
    • En la página de APIs, verifica que la API se haya publicado correctamente y que su URL y configuración de visibilidad sean correctas.
    • Si la API se sirve a través de una puerta de enlace de API privada, revisa la instalación de la puerta de enlace y la conectividad para detectar errores o configuraciones incorrectas.

La URL del servicio excede la longitud máxima (HTTP 414)

  • Síntoma: La puerta de enlace de API devuelve:

    414 URI Too Large

  • Posible causa: La URL del servicio construida (incluyendo URL base, ruta del servicio y cualquier parámetro de ruta o consulta) excede 8,000 caracteres.

  • Resolución:
    • Reduce la longitud de la URL del servicio acortando la ruta del servicio o dividiendo la API en múltiples puntos de conexión.
    • Para APIs proxy, confirma que la combinación de la URL base y todas las rutas de servicio definidas se mantenga dentro del límite de 8,000 caracteres.

API proxy: Los parámetros de ruta de servicio requieren un documento OpenAPI

  • Síntoma: Configurar una ruta de servicio de API proxy con parámetros de ruta (por ejemplo, /resource/{id}) falla cuando se ingresa manualmente, porque el campo no acepta caracteres de llave.
  • Posible causa: Las rutas de servicio definidas manualmente en APIs proxy no admiten los caracteres { y } utilizados para definir parámetros de ruta.
  • Resolución: Para usar parámetros de ruta en una ruta de servicio de API proxy, proporciona un documento OpenAPI que defina las rutas y sus parámetros. API Manager descubre automáticamente las rutas y sus parámetros de la especificación OpenAPI en lugar de requerir que se ingresen manualmente.

No se puede eliminar una API en API Manager

  • Síntoma: Eliminar una API en API Manager falla: la interfaz muestra un error genérico y la API no se elimina. El fallo ocurre en el navegador antes de que cualquier solicitud de eliminación llegue al servidor y aparece como un TypeError de JavaScript en la consola del desarrollador del navegador.
  • Posible causa: El rol del usuario no tiene el permiso de Admin. Eliminar una API primero verifica con qué Grupos de API está asociada la API, y ver la página de Grupos de API requiere el permiso de Admin: un rol con solo acceso de entorno de Escritura puede abrir la página pero no puede leer su contenido. Cuando el rol no puede leer los grupos de API, esa verificación recibe un valor que la interfaz no puede procesar y la eliminación no se completa.
  • Resolución: Haz que un usuario cuyo rol tenga el permiso de permiso de rol de Admin realice la eliminación. Otorgar al rol afectado el permiso de Admin también funciona, pero eso es una elevación amplia a nivel de organización, por lo que es preferible que un administrador existente elimine la API.

El entorno de API no se puede cambiar después de la creación

  • Síntoma: Se creó una API en el entorno incorrecto y es necesario moverla, pero el campo de entorno no es editable.
  • Causa posible: El entorno se establece en el momento de la creación de la API y no se puede cambiar después.
  • Resolución:
    • Para mover una API personalizada o proxy a un entorno diferente, clona la API desde la página de APIs y selecciona el entorno correcto durante la clonación.
    • Alternativamente, exporta la API desde su entorno actual e importala al entorno de destino.

CORS habilitado: las solicitudes OPTIONS se ejecutan sin autenticación

  • Síntoma: Después de habilitar CORS en una API personalizada o proxy, el método HTTP OPTIONS procesa solicitudes sin autenticación.
  • Causa posible: Habilitar CORS hace que las operaciones que utilizan el método OPTIONS se ejecuten sin autenticación. Esto es necesario para admitir solicitudes de verificación previa del navegador, pero significa que cualquier solicitud OPTIONS llega a la operación sin pasar por el perfil de seguridad.
  • Resolución:
    • Si la API no utiliza OPTIONS para operaciones sensibles, no se requiere ninguna acción. Este es el comportamiento esperado cuando CORS está habilitado.
    • Si se requiere el manejo autenticado de OPTIONS, deshabilita CORS en la API o reestructura la operación para detectar y manejar explícitamente las solicitudes de verificación previa no autenticadas.

API proxy en la nube: la API de destino debe ser accesible públicamente

  • Síntoma: Una API proxy que utiliza la puerta de enlace de API en la nube alojada en Jitterbit devuelve errores o no puede alcanzar la API de destino.
  • Causa posible: Al utilizar la puerta de enlace de API en la nube, la API que se está utilizando como proxy debe ser accesible desde Internet público. Las APIs detrás de un firewall o en una red privada no pueden ser alcanzadas por la puerta de enlace en la nube.
  • Resolución:
    • Confirma que la API de destino es accesible desde Internet público, incluso si está asegurada.
    • Si la API de destino debe permanecer detrás de un firewall, implementa una puerta de enlace de API privada en la misma red privada en lugar de utilizar la puerta de enlace de API en la nube.
    • Para incluir en la lista de permitidos las direcciones IP de la puerta de enlace en la nube de modo que la puerta de enlace pueda acceder a la API utilizada como proxy, consulta Información de lista de permitidos.

La configuración Mostrar cargas útiles de solicitud y respuesta no tiene efecto para APIs proxy

  • Síntoma: El botón de alternancia Mostrar cargas útiles de solicitud y respuesta en registros aparece en la configuración de una API proxy, pero habilitarlo no tiene efecto en la salida del registro.
  • Causa posible: El registro de cargas útiles de solicitud y respuesta no es compatible con APIs proxy. El botón de alternancia es visible en la interfaz de configuración pero no funciona para este tipo de API.
  • Resolución: Para capturar cargas útiles de solicitud y respuesta, utiliza una API personalizada que llame al mismo punto de conexión, donde la configuración Mostrar cargas útiles de solicitud y respuesta en registros es compatible.

Rendimiento y tiempos de espera

HTTP 504 Gateway Timeout

  • Síntoma: Las llamadas de API devuelven:
504 Gateway Timeout

Esto típicamente ocurre después de que se agota la ventana de tiempo de espera de la puerta de enlace (30 a 180 segundos, dependiendo de la configuración de Timeout de la API).

  • Posibles causas:

    • La URL de la API está mal formada, o los parámetros de ruta no se están manejando correctamente, lo que causa que la puerta de enlace falle al enrutar la solicitud.
    • La operación de backend o el servicio externo es demasiado lento para responder dentro de la ventana de tiempo de espera de la puerta de enlace, por ejemplo debido a cargas útiles grandes o lógica de transformación compleja.
    • La solicitud no se puede asignar a un agente disponible, por ejemplo porque el grupo de agentes está en concurrencia máxima o bajo carga pesada, por lo que se agota el tiempo de espera en la puerta de enlace antes de que se ejecute la operación. Una señal de este caso es que la solicitud fallida no tiene una entrada correspondiente en los registros de operación.

  • Resolución:

    • Verifica que la URL de la API esté correctamente formada. Si la API utiliza parámetros de ruta, considera agregar un script a la operación que analice explícitamente la URL y capture los valores de los parámetros.
    • Si el tiempo de espera es causado por un backend lento, revisa la operación y su lógica de transformación para identificar cuellos de botella de rendimiento, particularmente cargas de datos grandes o llamadas externas lentas, y reduce el paso lento.
    • Si la operación genuinamente requiere más tiempo del que permite la configuración actual, aumenta el tiempo de espera en la pestaña de configuración de API. El tiempo de espera de la API (30 segundos por defecto, máximo 180 segundos) es independiente del tiempo de espera de la operación de Studio; el tiempo de espera de la operación se utiliza solo en agentes privados cuando la configuración EnableAPITimeout está habilitada en la configuración del agente.
    • Si la operación no puede completarse dentro del tiempo de espera máximo, o no se requiere una respuesta en tiempo real, rediseña la operación de la API para iniciar el trabajo de larga duración de forma asincrónica (por ejemplo, llamándola con RunOperation en modo asincrónico) para que la API pueda devolver una respuesta sin esperar a que se complete. Consulta Administrar operaciones asincrónicas.
    • Para tiempos de espera intermitentes, agrega reintentos para que una falla transitoria se reintente: utiliza la configuración de reintento integrada de la conexión HTTP v2 para llamadas salientes, o un bucle de reintento RunOperation con script con un retraso entre intentos.
    • Si los tiempos de espera se correlacionan con la carga del agente, revisa la capacidad del agente: ejecuta operaciones que sirven API en agentes separados de cargas de trabajo ETL pesadas, y agrega agentes al grupo si está saturado. Consulta Optimizar y mejorar el rendimiento de los agentes privados de Jitterbit.

La puerta de enlace privada devuelve una página 400 "verify Jitterbit Services" sin entrada de registro de API

  • Síntoma: Las solicitudes a través de una puerta de enlace de API privada fallan intermitentemente con una respuesta HTTP 400. En lugar de una respuesta de API normal, el llamador recibe una página de error HTML similar a:

    Error connecting to Jitterbit Services. Please verify that all Jitterbit Services are running on your Jitterbit Agent machine - including the Apache server and Process Engine.

    No aparece ninguna entrada en los registros de API para la solicitud fallida, porque la solicitud nunca llegó a una operación.

  • Posible causa: El grupo de agentes privados está sobrecargado y no tiene subprocesos de trabajo Apache disponibles para aceptar trabajos de la puerta de enlace de API privada. Cuando ningún subproceso de trabajo está libre, la transferencia de puerta de enlace a agente falla con un restablecimiento de conexión antes de que la solicitud pueda registrarse o ejecutarse.

  • Resolución:
    1. Agrega más agentes al grupo de agentes para distribuir la carga, y confirma que los hosts de agentes tengan suficiente CPU y memoria.
    2. Monitorea el uso de subprocesos de trabajo Apache de los agentes. Si la observabilidad nativa está habilitada, revisa los gráficos de Apache Thread Capability, Apache idle workers y Apache busy workers (consulta Dashboards) para confirmar si los subprocesos se están agotando durante las fallas.
    3. Si los agentes se quedan constantemente sin subprocesos de trabajo Apache incluso después de escalar, contacta al soporte de Jitterbit para revisar la capacidad de subprocesos de trabajo Apache de los agentes (la configuración MaxRequestWorkers). No cambies los archivos de configuración de Apache de Jitterbit a menos que lo indique el soporte de Jitterbit. Consulta Archivos de configuración de Apache.

Visualización y sincronización

El Portal de API no refleja los cambios del proyecto

  • Síntoma: El Portal de API muestra nombres o atributos de proyecto desactualizados después de que se renombra o actualiza un proyecto.
  • Causa posible: El Portal de API no se sincronizó automáticamente después de que se cambió el proyecto.
  • Resolución:
    1. Para actualizar todas las API personalizadas y proxy en el entorno, abre el Administrador de Portal y haz clic en Regenerar Documentos. Para actualizar una sola API, abre su pestaña Documentación en la página API y haz clic en Guardar y Publicar.
    2. Verifica que la información actualizada se refleje correctamente en el Portal de API.

Los cambios del perfil de seguridad tardan varios minutos en surtir efecto

  • Síntoma: Una API continúa comportándose como si una configuración de perfil de seguridad anterior estuviera activa, incluso después de que se haya actualizado y guardado el perfil.
  • Causa posible: Los perfiles de seguridad se almacenan en caché en la puerta de enlace de API. Los cambios en un perfil de seguridad activo no surten efecto inmediatamente.
  • Resolución:
    1. Espera varios minutos después de guardar un cambio de perfil de seguridad antes de probar la API afectada.
    2. Si el problema persiste después de 10 minutos, confirma que el cambio se guardó correctamente reabriendo el perfil de seguridad.

Eliminar una API no actualiza la documentación del Portal de API

  • Síntoma: Después de eliminar una API, su documentación de OpenAPI permanece visible en el Portal de API.
  • Causa posible: La documentación del Portal de API no se actualiza automáticamente cuando se elimina una API del Administrador de API.
  • Resolución:
    • Después de eliminar una API, abre el Administrador de Portal y elimina o actualiza manualmente la entrada de documentación de la API.
    • Alternativamente, usa la pestaña Documentación de la API antes de eliminarla para eliminar primero la entrada del Portal.

No se puede eliminar el perfil de seguridad mientras sigue asignado a una API publicada

  • Síntoma: El intento de eliminar un perfil de seguridad falla o la opción de eliminar no está disponible, incluso después de desasignar el perfil de una API.
  • Causa posible: Después de eliminar un perfil de seguridad de la configuración de una API, se debe guardar y volver a publicar la API antes de que el perfil se considere completamente desasignado. Hasta que se vuelva a publicar la API, el Administrador de API sigue considerando que el perfil está en uso.
  • Resolución:
    1. Después de desasignar el perfil de seguridad de la API, haz clic en Guardar y luego Publicar la API.
    2. Una vez que se haya vuelto a publicar la API con la configuración actualizada, el perfil de seguridad ya no se mostrará como en uso y podrá eliminarse.

Problemas de puerta de enlace privada

OAuth de 2 etapas vuelve a OAuth de 3 etapas en versiones de puerta de enlace privada anteriores a 10.48

  • Síntoma: Un perfil de seguridad configurado para OAuth de 2 etapas utiliza OAuth de 3 etapas en su lugar cuando se sirve a través de una puerta de enlace de API privada.
  • Causa posible: Las puertas de enlace de API privadas anteriores a la versión 10.48 no admiten OAuth de 2 etapas. Si la versión de la puerta de enlace es anterior a 10.48, el perfil de seguridad vuelve a OAuth de 3 etapas incluso cuando se configura OAuth de 2 etapas.
  • Resolución:
    1. Verifica la versión de la puerta de enlace de API privada que sirve la API.
    2. Actualiza la puerta de enlace a la versión 10.48 o posterior para habilitar la compatibilidad con OAuth de 2 etapas.

ALB multi-gateway: Todos los contenedores deben estar en el mismo host

  • Síntoma: En un entorno multi-gateway containerizado detrás de un balanceador de carga de aplicaciones (ALB), las llamadas a la API fallan intermitentemente o no se pueden recuperar las cargas útiles aunque las puertas de enlace individuales parezcan estar en buen estado.
  • Causa posible: Al usar una puerta de enlace de API privada containerizada con un ALB, todos los contenedores de la puerta de enlace deben ejecutarse en la misma máquina host. Los contenedores implementados en diferentes hosts no pueden coordinar la recuperación de cargas útiles, lo que causa fallos intermitentes.
  • Resolución:
    1. Confirma que todos los contenedores de la puerta de enlace de API privada en el grupo se ejecutan en el mismo host físico o virtual.
    2. Si los contenedores están distribuidos en varios hosts, consolídalos en un único host.
    3. Para implementaciones multi-host, revisa la configuración de ALB en la guía de instalación de la puerta de enlace para conocer los requisitos de configuración adicionales.

Puerta de enlace privada: La configuración SSL personalizada se sobrescribe con las actualizaciones

  • Síntoma: Después de actualizar una puerta de enlace de API privada, la configuración personalizada de protocolo SSL o cifrado ya no se aplica y la puerta de enlace revierte al comportamiento TLS predeterminado.
  • Causa posible: El proceso de actualización de la puerta de enlace de API privada sobrescribe el archivo de configuración local (/usr/local/openresty/nginx/conf/onpremise.conf). Cualquier cambio manual en este archivo, incluidas las restricciones de protocolo SSL personalizado o listas de cifrado, se pierden durante la actualización.
  • Resolución:
    1. Antes de actualizar la puerta de enlace de API privada, realiza una copia de seguridad del archivo de configuración local.
    2. Después de que se complete la actualización, vuelve a aplicar la configuración SSL personalizada al nuevo archivo de configuración.

Puerta de enlace privada devuelve HTTP 507 o "No such file or directory"

  • Síntoma: Los puntos de conexión de la puerta de enlace de API privada devuelven 507 Insufficient Storage. Los registros de la puerta de enlace muestran:

    could not open payload file: No such file or directory

    incluso cuando hay amplio espacio en disco en los hosts de la puerta de enlace.

  • Causa posible: Aquí, 507 significa que la puerta de enlace no pudo abrir el archivo de carga útil o respuesta alojado para la solicitud; no necesariamente significa que el host se haya quedado sin almacenamiento. En una puerta de enlace de API privada multi-nodo detrás de un balanceador de carga, esto puede ocurrir cuando el nodo que atiende una solicitud no puede acceder a un archivo alojado que otro nodo creó, porque esos archivos son locales a cada nodo.

  • Resolución:

    1. Confirma que los hosts de la puerta de enlace no se han quedado sin almacenamiento verificando el uso de disco e inodos (df -h y df -i). Libera espacio y vuelve a probar solo si realmente están llenos.
    2. Si la puerta de enlace se ejecuta como varios nodos detrás de un balanceador de carga, confirma que el balanceador de carga enruta cada solicitud y su respuesta de manera consistente al mismo nodo, porque los archivos de carga útil y respuesta alojados son locales al nodo que los creó. Para puertas de enlace containerizadas, consulta ALB multi-gateway: Todos los contenedores deben estar en el mismo host.
    3. Si el error persiste, habilita el registro de seguimiento en la puerta de enlace (establece traceLogsEnabled en true en la configuración de la puerta de enlace) y contacta con el soporte de Jitterbit con los registros de seguimiento resultantes, los registros de la puerta de enlace (/opt/jitterbit/var/log/api-gateway), los registros de NGINX u OpenResty, y la salida de ls -lR para los directorios hosted-files en cada nodo. El soporte puede verificar condiciones del servidor que no son configurables por el cliente, como la asignación de host a entorno, entradas de dominio privado obsoletas y permisos de archivo.

La instalación o actualización de la puerta de enlace privada falla por dependencias faltantes

  • Síntoma: Al ejecutar yum install para instalar o actualizar una puerta de enlace de API privada de Linux (RPM) a la versión 10.62 o posterior, se producen errores de dependencias faltantes:

    Nothing provides geoip-devel needed by jitterbit-api-gateway-11.x.x-x.x86_64
Nothing provides libGeoIP.so.1()(64bit) needed by jitterbit-api-gateway-11.x.x-x.x86_64

  • Causa posible: La puerta de enlace de API privada versión 10.62 y posteriores requieren los paquetes geoip-devel y libGeoIP, que proporciona el repositorio EPEL. La instalación documentada habilita EPEL antes de instalar la puerta de enlace. El error ocurre cuando se omite ese paso o cuando el host de la puerta de enlace no tiene acceso a internet y no puede alcanzar EPEL para descargar los paquetes.

  • Resolución:

    • En un host de puerta de enlace con acceso a internet, habilita el repositorio EPEL antes de instalar la puerta de enlace, como se describe en Instalar una puerta de enlace de API privada: ejecuta yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm y luego vuelve a ejecutar la instalación de la puerta de enlace.
    • En un host aislado sin acceso a internet, instalar solo el paquete epel-release solo agrega la definición del repositorio; no descarga los paquetes geoip-devel y libGeoIP. En una máquina con acceso a internet, descarga esos paquetes y sus dependencias transitivas, transfierelos al host de la puerta de enlace e instálalos en orden de dependencia con yum install <package.rpm> antes de volver a ejecutar la instalación de la puerta de enlace.

La autoprueba de la puerta de enlace privada devuelve "Failure, test call to API failed"

  • Síntoma: La utilidad de autoprueba de línea de comandos de la puerta de enlace de API privada devuelve:

    Failure, test call to API failed

  • Causa posible: En las versiones 11.30 y anteriores de la puerta de enlace de API privada, la utilidad de autoprueba crea una API de prueba que carece de campos requeridos (Nombre del servicio y Ruta), lo que causa que la llamada de prueba falle.

  • Resolución:
    • Actualiza la puerta de enlace de API privada a la versión 11.31 o posterior, lo que resuelve esto automáticamente.
    • Si no es posible actualizar inmediatamente: abre la configuración de API para la API denominada ApiGatewayTest, completa el campo Nombre del servicio con cualquier valor (por ejemplo, service), establece Ruta en /, guarda y publica, luego vuelve a ejecutar la utilidad de autoprueba.

Análisis y comportamiento de API

OData $count o $inlinecount devuelve un error cuando no hay registros coincidentes

  • Síntoma: Una consulta de servicio OData que utiliza las opciones de consulta del sistema $count o $inlinecount devuelve un error en lugar de 0 cuando ningún registro coincide con el filtro.
  • Causa posible: Por defecto, un servicio OData devuelve un error en lugar de 0 cuando una consulta $count o $inlinecount no coincide con ningún registro.
  • Resolución: En agentes privados que ejecutan la versión 11.32 o posterior, establece el parámetro OData $noErrorOnZeroCount en true en la configuración del servicio OData. Esto hace que las consultas $count devuelvan 0 en lugar de un error cuando ningún registro coincide.

API de proxy: guiones en encabezados de solicitud reemplazados por guiones bajos

  • Síntoma: Una operación de API de proxy recibe encabezados de solicitud con guiones reemplazados por guiones bajos (por ejemplo, X-Custom-Header llega como X_Custom_Header), lo que causa que las búsquedas de encabezados fallen.
  • Causa posible: Las API de proxy tienen una configuración disable-hyphen-replacement que controla si los guiones en los nombres de encabezados de solicitud se reemplazan con guiones bajos. Para nuevas API de proxy, esta configuración tiene como valor predeterminado true (reemplazo deshabilitado). Las API de proxy más antiguas pueden tenerla establecida en false, lo que causa el reemplazo.
  • Resolución:
    • En la configuración de API de proxy, verifica la configuración del encabezado disable-hyphen-replacement. Para preservar guiones en los nombres de encabezados, asegúrate de que la configuración sea true.
    • Si la API de proxy se creó antes de que se introdujera este valor predeterminado y el reemplazo ocurre inesperadamente, actualiza la configuración a true y vuelve a publicar la API.

Los registros de operación no son visibles para operaciones activadas por API cuando el modo de depuración está desactivado

  • Síntoma: Después de llamar a una API, el registro de API muestra que la llamada se ejecutó correctamente, pero no aparece ningún registro de operación en la página Runtime para la operación que activó la API. Las llamadas a WriteToOperationLog desde dentro de la operación tampoco producen entradas de registro visibles.
  • Causa posible: Cuando se activa una operación a través de una API publicada, las ejecuciones correctas no aparecen en los registros de operación de forma predeterminada. Las operaciones fallidas siempre se registran; solo los registros de operación correctos y cualquier salida de WriteToOperationLog de ejecuciones correctas se ocultan. Las ejecuciones correctas aparecen solo cuando Habilitar modo de depuración hasta (una configuración de API Manager) u Operación de registro de depuración (una configuración de agente) está activa.
  • Resolución:
    1. Para ver los registros de operación correctos y la salida de WriteToOperationLog, activa Habilitar modo de depuración hasta para la API en la pestaña de configuración de API, o habilita Operación de registro de depuración en el agente.
    2. Para capturar también los datos sin procesar de solicitud y respuesta y las cargas útiles, activa Habilitar modo de depuración hasta (como en el paso 1), o combina Operación de registro de depuración con Mostrar cargas útiles de solicitud y respuesta en registros y Registro detallado. Los datos que captura cada configuración dependen de la combinación habilitada; para el desglose completo, consulta Datos de solicitud y respuesta de API.
    3. Desactiva el modo de depuración después de recopilar los registros que necesitas, ya que dejarlo activado aumenta el volumen de registros.

Carga útil de API disponible en el agente durante 2 días

  • Síntoma: Un flujo de trabajo que recupera una carga útil de solicitud de API del agente más de 2 días después de que se llamó a la API no puede encontrar la carga útil.
  • Causa posible: Las cargas útiles de solicitud de API para API personalizadas y servicios OData se almacenan en el agente durante un máximo de 2 días. Después de ese período, la carga útil está disponible solo si la operación ya la escribió en un conector de almacenamiento persistente (como Almacenamiento temporal, Recurso compartido de archivos o una base de datos).
  • Resolución:
    • Diseña operaciones que consuman cargas útiles de solicitud de API para procesar los datos inmediatamente cuando se llama a la API en lugar de diferir la recuperación de la carga útil.
    • Si la carga útil debe retenerse para un procesamiento más prolongado, escríbela en una ubicación de almacenamiento persistente en la operación inicial activada por API.

La página Registros de API retiene las selecciones de filtro anteriores

  • Síntoma: La página Registros de API no muestra las entradas de registro esperadas aunque la API se esté ejecutando correctamente.
  • Causa posible: La página Registros de API recuerda las selecciones de filtro de la sesión anterior. Un filtro aplicado previamente puede estar ocultando los resultados esperados.
  • Resolución: En la página Registros de API, revisa todos los filtros activos y borra los que puedan estar excluyendo las entradas esperadas.

Las API no publicadas no aparecen en el menú desplegable de API de Analytics

  • Síntoma: Una API no aparece en el menú desplegable API en la página Analytics, por lo que no se pueden filtrar los datos de analytics de esa API.
  • Causa posible: Solo las API publicadas actualmente aparecen en el menú desplegable API. Las API que se han dejado de publicar se excluyen del menú desplegable incluso si existen registros de API para esas API.
  • Resolución:
    • Confirma que la API se ha publicado. Para ver datos de analytics, la API debe estar en estado publicado.
    • Para ver entradas de registro de una API no publicada, usa la página Registros de API en su lugar. Los datos de registro permanecen disponibles allí pero no se pueden filtrar por nombre de API.

Limitación de velocidad

Error 429: Se excedió la asignación mensual de llamadas a API

  • Síntoma: Todas las API de la organización devuelven de repente errores HTTP 429.
  • Causa posible: La organización ha agotado su asignación mensual de llamadas a API según lo definido por su licencia. Cuando se excede la asignación, se rechaza todas las llamadas a API con una respuesta 429 durante el resto del mes.
  • Resolución:
    • Verifica el recuento actual de llamadas contra tu asignación mensual en la página de APIs. La asignación se reinicia el primer día del mes siguiente.
    • Para evitar alcanzar el límite, configura límites de velocidad a nivel de entorno o perfil de seguridad usando la configuración Llamadas por minuto para distribuir la carga e imponer límites de consumo por consumidor.
    • Para aumentar la asignación mensual de tu organización, contacta a tu Gerente de Éxito del Cliente.

Error 429: IP del consumidor no está en el rango de IP de confianza

  • Síntoma: Un consumidor o aplicación específica recibe errores HTTP 429 al llamar a una API, mientras que otros consumidores pueden llamar a la misma API exitosamente.
  • Causa posible: El perfil de seguridad asignado a la API tiene grupos de IP de confianza configurados. Se rechaza las solicitudes de direcciones IP fuera de los rangos permitidos con una respuesta 429.
  • Resolución:
    1. Abre el perfil de seguridad asignado a la API y revisa su configuración de grupo de IP de confianza.
    2. Agrega la dirección IP del consumidor o el rango de direcciones a un grupo de IP de confianza existente, o crea un nuevo grupo de IP de confianza que incluya las direcciones requeridas.

Límite de velocidad a nivel de plataforma: 200 solicitudes por minuto

  • Síntoma: Las API alojadas en la puerta de enlace de API en la nube administrada por Jitterbit se limitan o se rechazan con una respuesta 429 Too Many Requests bajo tráfico alto, incluso cuando no se han alcanzado los límites de velocidad del perfil de seguridad.
  • Causa posible: La puerta de enlace de API en la nube administrada por Jitterbit impone un límite a nivel de plataforma de 200 solicitudes de API por minuto por organización, compartido entre todos los tipos de API (personalizada, proxy y OData). Este límite no se aplica a las puertas de enlace de API privadas.
  • Resolución:
    • Revisa tus patrones de tráfico de API y distribuye las llamadas a lo largo del tiempo si es posible para mantenerte dentro del límite de 200 solicitudes por minuto.
    • Si tu caso de uso requiere un rendimiento sostenido por encima de este límite, implementa una puerta de enlace de API privada donde el rendimiento se determina por la capacidad del servidor host en lugar de un límite a nivel de plataforma.

Red y conectividad

Zscaler o firewall que intercepta SSL bloquea el acceso a API

  • Síntoma: Las llamadas a API fallan con errores de certificado, o los puntos finales de backend no pueden alcanzar las API protegidas con TLS cuando se enrutan a través de una red administrada por Zscaler o similar que inspecciona SSL.
  • Causas posibles:
    • Zscaler y proxies de seguridad similares realizan inspección SSL/TLS interceptando tráfico HTTPS y volviéndolo a firmar con su propio certificado de CA. Los sistemas cliente que no confían en la CA raíz de Zscaler rechazan la conexión.
    • Importar manualmente el certificado de Jitterbit en el almacén de confianza no es una solución confiable: cuando Jitterbit renueva su certificado, la copia importada manualmente se vuelve obsoleta y rompe la conexión nuevamente.
  • Resolución:
    • Instala el certificado de CA raíz de Zscaler en el almacén de confianza del sistema operativo o navegador en los sistemas que realizan las llamadas a API, para que se confíe en los certificados re-firmados por Zscaler.
    • Para herramientas como curl, wget u openssl, configúralas para usar el proxy HTTP definido en el entorno de Zscaler.
    • Solicita una excepción de política de Zscaler para los nombres de host de la puerta de enlace de API de Jitterbit para omitir la inspección SSL para esos destinos específicos.
    • Revisa las reglas del archivo PAC (proxy auto-configuration) de la organización para confirmar que los puntos finales de Jitterbit se manejan correctamente.
    • No importes manualmente el certificado hoja de Jitterbit en un almacén de confianza como solución alternativa: usa la CA raíz de Zscaler en su lugar para evitar problemas cuando Jitterbit renueva su certificado.

Please paste the Markdown content you'd like me to translate.