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 integración, automatización, gestión de API, EDI y problemas de 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 los 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, que pueden ayudar a reducir la causa.

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

  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 una ventana fija de solución de problemas, utiliza Registro detallado o Mostrar cargas útiles de solicitud y respuesta en registros para servicios personalizados y OData.

Verificar el estado del sistema de Jitterbit

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

Errores de autenticación y seguridad

Microsoft Entra ID OAuth: 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 etapas 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 causan que el URI de redireccionamiento 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 cambia su 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 redireccionamiento que API Manager genera para el perfil renombrado.

Microsoft Entra ID OAuth de dos etapas: Error OAUTH_INVALID_TOKEN_CODE

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

    Failed to validate authentication token - HttpErrorResponse: OAUTH_INVALID_TOKEN_CODE

  • Posible causa: El claim 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 identificador de aplicación en el registro de aplicaciones de Azure está mal configurado, o el scope de OAuth que solicita el cliente no coincide con el URI registrado.

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

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 aplicaciones del perfil de seguridad aún está configurado para usar Azure AD Graph API, que Microsoft retiró el 30 de junio de 2025. Los registros de aplicaciones que no migraron a Microsoft Graph fallan al realizar solicitudes.
  • Resolución:
    1. En Azure Portal, migra el registro de aplicaciones 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 de 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 son compatibles con OAuth de 2 patas.
  • Resolución: Usa un perfil de seguridad de OAuth 2.0 de 3 patas para API que se autentiquen 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 una herramienta de API REST) falla cuando el perfil de seguridad de la API usa autenticación básica.
  • Posible causa: Microsoft Copilot Studio no es compatible con 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, luego reconéctala en Microsoft Copilot Studio. Consulta Conectar un agente de Jitterbit AI 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 Management Console, 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 los cambios.
    3. El botón New API ahora debería estar visible para ese entorno.

  • Síntoma: Una credencial de autenticación básica en caché de una solicitud anterior puede afectar una llamada de API posterior de cualquiera de estas maneras:

    • 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.
    • Una API proxy u OData service asignada a un perfil de seguridad de autenticación Basic devuelve una respuesta exitosa sin solicitar credenciales.

  • 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 en caché primero. Si las credenciales en caché no coinciden con ningún perfil de seguridad asignado, 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. Si coinciden, la solicitud se completa sin un nuevo mensaje.

  • Resolución:

    1. Borra las cookies y el caché del navegador, o cambia a una ventana de navegación en incógnito 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 comportamiento desaparece, se trata de almacenamiento en caché de credenciales del lado del cliente y no de 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.

Error INVALID_TRIGGER_USER o TRIGGER_USER_TOO_LONG

  • Síntoma: Una llamada de API que utiliza un perfil de seguridad con autenticación básica o una configuración Custom de Logging falla con un error INVALID_TRIGGER_USER o TRIGGER_USER_TOO_LONG, aunque las mismas credenciales o valor de encabezado funcionaron anteriormente.

  • Causa posible: El valor utilizado para identificar a quien realiza la llamada de la solicitud viola una regla de validación: contiene un carácter no permitido (INVALID_TRIGGER_USER) o excede 256 caracteres (TRIGGER_USER_TOO_LONG).

    • Para autenticación básica con la configuración de Logging predeterminada, este valor es el campo User name del perfil de seguridad.
    • Para una configuración Custom de Logging, es el valor que la aplicación que realiza la llamada envía en el encabezado configurado.

La validación de caracteres se agregó en la versión 12.10 de Harmony, y el límite de longitud se agregó en la versión 12.11 de Harmony. Una API gateway privada que ejecuta una versión anterior no aplica la validación correspondiente, por lo que cualquiera de estos errores puede aparecer por primera vez después de actualizar la gateway, aunque la configuración del perfil de seguridad no haya cambiado.

A partir de la versión 12.12 de Harmony, el campo Nombre de usuario del perfil de seguridad rechaza los caracteres no permitidos, por lo que ya no se puede guardar un perfil de seguridad que los contenga. Para la autenticación Basic con la configuración predeterminada de Logging, INVALID_TRIGGER_USER se aplica únicamente a los perfiles de seguridad guardados antes de esa versión.

  • Solución:
    • Para la autenticación Basic con la configuración predeterminada de Logging, edita el campo Nombre de usuario del perfil de seguridad para eliminar los caracteres no permitidos o acortarlo a 256 caracteres o menos, según sea aplicable, y luego actualiza las credenciales en cualquier aplicación que llame y que haga referencia al nombre de usuario anterior.
    • Para una configuración de Custom Logging, actualiza la aplicación que llama para enviar un valor de encabezado que no contenga caracteres no permitidos y tenga 256 caracteres o menos.

401 Unauthorized con una lista de permitidos de IP válida (caché obsoleta)

  • 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 rangos de IP heredados en el perfil de seguridad está anulando los grupos de IP de confianza activos.
  • Solución: Migra el perfil de seguridad de rangos de IP heredados al modelo de Grupos de IP de confianza, 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 (una solicitud de confirmación te advierte de esto), por lo que migra las IPs a un grupo de IP de confianza en lugar de desactivar la configuración para limpiar el caché.

Salesforce en Hyperforce: Las llamadas a una API se rechazan después de que cambian las direcciones IP de Salesforce

  • Síntoma: Las llamadas desde Salesforce a una API (mensajes salientes, llamadas de Apex, Salesforce Connect o acciones invocables) se rechazan después de que la organización de Salesforce se migra a Hyperforce, la infraestructura de nube pública de Salesforce. El perfil de seguridad de la API tiene Trust requests only from the following IP ranges habilitado con un grupo de IP de confianza que lista las direcciones IP de Salesforce.

  • Causa posible: Los grupos de IP de confianza coinciden con la dirección IP de origen de una solicitud, y las direcciones que una organización de Salesforce en Hyperforce usa para llamadas salientes cambian con el tiempo. Un grupo que lista un conjunto fijo de direcciones de Salesforce deja de coincidir.

  • Solución: Salesforce recomienda autenticar las llamadas en tu red en lugar de permitir sus direcciones IP de origen:

    1. Abre el perfil de seguridad asignado a la API y establece su Tipo de autenticación en Clave de API. Configura la llamada de Salesforce para enviar la clave en un encabezado de solicitud, no en un parámetro de consulta, para que no se registre en las URL de las solicitudes. OAuth 2.0 también está disponible, aunque con Salesforce como proveedor de identidad, el único flujo es 3-legged, que requiere interacción manual.

  • Después de que la llamada se autentica correctamente, desasigna el grupo de IP de confianza que enumera las direcciones de Salesforce, para que los cambios de direcciones posteriores ya no afecten la API. Desasigna el grupo en lugar de desactivar Confiar solo en solicitudes de los siguientes rangos de IP, que elimina permanentemente cualquier rango de IP heredado aún presente en el perfil.

    Si tu organización requiere lista de permitidos de IP, Salesforce publica sus rangos de Hyperforce como una lista dinámica en ip-ranges.salesforce.com/ip-ranges.json, anunciando adiciones con anticipación. Esa lista cambia cada vez que Salesforce modifica sus direcciones, así que mantener una lista de permitidos actual significa rastrear el archivo y actualizar el grupo de IP de confianza para que coincida. Se rechazan las llamadas desde una dirección agregada después de la última actualización del grupo. Estas direcciones también se comparten entre organizaciones de Salesforce, así que agregarlas a la lista de permitidos confirma de dónde proviene una solicitud, no que provenga de tu organización. Para la orientación completa de Salesforce, incluyendo SSL bidireccional (mTLS), Proveedores de autenticación y aplicaciones conectadas, consulta Retain uninterrupted access to Salesforce services on Hyperforce.

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 del Administrador de API, verifica los conteos de URLs de API personalizadas utilizadas y URLs de API proxy utilizadas, que se muestran en la parte superior de la página, con los totales permitidos por tu suscripción. Desactiva la publicación o elimina las APIs que ya no necesites para liberar URLs de API (las APIs en borrador no cuentan para el límite). Para aumentar el límite, contacta a tu Gerente de éxito del cliente.

La API publicada devuelve 404 No encontrado

  • Síntoma: Llamar a una API publicada devuelve un error 404.
  • Posibles causas:
    • El límite de Solicitudes por minuto en el perfil de seguridad asignado se establece en cero, bloqueando todas las solicitudes. Un cambio en el nivel de suscripción de la organización puede restablecer este límite, así que una API que funcionaba previamente 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 Solicitudes por minuto se establece 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 previsto.
    • En la página APIs, verifica que la API se haya publicado exitosamente 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, verifica 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

  • Causa posible: La URL del servicio construida (incluida la URL base, la ruta del servicio y cualquier parámetro de ruta o consulta) excede 8,000 caracteres.

  • Resolución:
    • Reducir la longitud de la URL del servicio acortando la ruta del servicio o dividiendo la API en varios puntos de conexión.
    • Para API proxy, confirmar 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: La configuración de 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 llaves.
  • Causa posible: Las rutas de servicio definidas manualmente en API proxy no admiten los caracteres { y } utilizados para definir parámetros de ruta.
  • Resolución: Para utilizar parámetros de ruta en una ruta de servicio de API proxy, proporcionar un documento OpenAPI que defina las rutas y sus parámetros. API Manager detecta automáticamente las rutas y sus parámetros desde la especificación OpenAPI en lugar de requerir que se ingresen manualmente.

No se puede eliminar una API en API Manager

  • Síntoma: La eliminación de una API en API Manager falla: la interfaz muestra un error genérico y la API no se elimina. El error 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.
  • Causa posible: El rol del usuario no tiene el permiso de Administrador. La eliminación de una API primero verifica con cuáles Grupos de API está asociada la API, y ver la página Grupos de API requiere el permiso de Administrador: 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: Hacer que un usuario cuyo rol tenga el permiso de rol de Administrador realice la eliminación. Otorgar al rol afectado el permiso de Administrador también funciona, pero eso es una elevación amplia a nivel de la organización, así que es preferible que un administrador existente elimine la API.

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

  • Síntoma: Se creó una API en el entorno incorrecto y necesita moverse, 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, clonar la API desde la página de APIs y seleccionar el entorno correcto durante la clonación.
    • Como alternativa, exportar la API de su entorno actual e importarla 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 acción. Este es el comportamiento esperado cuando CORS está habilitado.
    • Si se requiere manejo autenticado de OPTIONS, deshabilitacr CORS en la API o reestructurar la operación para detectar y manejar explícitamente 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á siendo proxy debe ser accesible desde internet público. Las API detrás de un firewall o en una red privada no se pueden alcanzar con la puerta de enlace en la nube.
  • Resolución:
    • Confirma que la API de destino es accesible desde internet público, aunque 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 a fin de que la puerta de enlace pueda acceder a la API proxy, consulta Información de la lista de permitidos.

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

  • Síntoma: El conmutador 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 de registros.
  • Causa posible: El registro de cargas útiles de solicitud y respuesta no se admite para APIs proxy. El conmutador 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 se admite la configuración Mostrar cargas útiles de solicitud y respuesta en registros.

Rendimiento y tiempos de espera

HTTP 504 Gateway Timeout

  • Síntoma: Las llamadas de API devuelven:

    504 Gateway Timeout

    Esto generalmente ocurre después de la ventana de tiempo de espera de la puerta de enlace (30 a 180 segundos, según la configuración de Tiempo de espera de la API).

  • Causas posibles:

    • 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.
    • No se puede asignar la solicitud a un agente disponible, por ejemplo, porque el grupo de agentes está con concurrencia máxima o bajo carga pesada, por lo que 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 operaciones.

  • 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 se debe a un backend lento, revisa la operación y su lógica de transformación para detectar cuellos de botella de rendimiento, particularmente cargas útiles de datos grandes o llamadas externas lentas, y reduce el paso lento.
    • Si la operación realmente requiere más tiempo del que permite la configuración actual, aumenta el tiempo de espera en la pestaña de configuración de la 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 termine. Consulta Administrar operaciones asincrónicas.
    • Para tiempos de espera intermitentes, agrega reintentos de modo que se vuelva a intentar una falla transitoria: utiliza la configuración de reintento integrada de la conexión HTTP v2 para llamadas salientes, o un bucle de reintento de RunOperation con script con una demora 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, quien realiza la llamada 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 de la solicitud fallida, porque la solicitud nunca llegó a una operación.

  • Causa posible: El grupo de agentes privados está sobrecargado y no tiene hilos de trabajo Apache disponibles para aceptar trabajos de la puerta de enlace de API privada. Cuando no hay hilos disponibles, el intercambio entre puerta de enlace y agente falla con un reinicio 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 los agentes tienen suficiente CPU y memoria.
    2. Monitorea el uso de hilos de trabajo Apache de los agentes. Si la observabilidad nativa está habilitada, revisa los gráficos Apache Thread Capability, Apache idle workers y Apache busy workers (consulta Dashboards) para confirmar si los hilos se están agotando durante las fallas.
    3. Si los agentes se quedan consistentemente sin hilos de trabajo Apache incluso después de escalar, contacta al soporte de Jitterbit para revisar la capacidad de hilos 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 ha renombrado o actualizado 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 APIs personalizadas y proxy en el entorno, abre el Administrador de portales y haz clic en Regenerate Docs. Para actualizar una única API, abre su pestaña Documentation en la página APIs y haz clic en Save & Publish.
    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 antigua estuviera activa, incluso después de que se ha 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.

La eliminación de 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 portales y elimina manualmente o actualiza la entrada de documentación de la API allí.
    • Alternativamente, usa la pestaña Documentation de la API antes de eliminarla para eliminar primero la entrada del Portal.

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

  • Síntoma: Al intentar eliminar un perfil de seguridad, la operación falla o la opción de eliminación no está disponible, incluso después de desasignar el perfil de una API.
  • Causa posible: Después de remover un perfil de seguridad de la configuración de una API, se debe guardar y republicar la API antes de que el perfil se considere completamente desasignado. Hasta que se republique la API, API Manager sigue tratando el perfil como en uso.
  • Resolución:
    1. Después de desasignar el perfil de seguridad de la API, haz clic en Guardar y luego en Publicar la API.
    2. Una vez que la API se haya republicado con la configuración actualizada, el perfil de seguridad ya no se mostrará como en uso y podrá ser eliminado.

Problemas de puerta de enlace privada

OAuth de 2 pasos regresa a 3 pasos en versiones de puerta de enlace privada anteriores a 10.48

  • Síntoma: Un perfil de seguridad configurado para OAuth de 2 pasos utiliza OAuth de 3 pasos 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 pasos. Si la versión de la puerta de enlace es anterior a 10.48, el perfil de seguridad regresa a OAuth de 3 pasos aunque esté configurado OAuth de 2 pasos.
  • 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 pasos.

ALB de múltiples puertas de enlace: Todos los contenedores deben estar en el mismo host

  • Síntoma: En un entorno de múltiples puertas de enlace en contenedores detrás de un equilibrador de carga de aplicaciones (ALB), las llamadas a API fallan intermitentemente o no se pueden recuperar cargas útiles, aunque las puertas de enlace individuales parezcan estar saludables.
  • Causa posible: Al utilizar una puerta de enlace de API privada en contenedor 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 múltiples hosts, consolídalos en un único host.
    3. Para implementaciones de múltiples hosts, revisa la configuración de ALB en la guía de instalación de la puerta de enlace para conocer requisitos de configuración adicionales.

Puerta de enlace privada: La configuración SSL personalizada se sobrescribe durante 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). Los cambios manuales en este archivo, incluidas las restricciones personalizadas de protocolo SSL o listas de cifrado, se pierden durante la actualización.
  • Resolución:
    1. Antes de actualizar la puerta de enlace de API privada, haz 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.

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

  • Síntoma: Los extremos de la puerta de enlace privada de API 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 privada de API de varios nodos detrás de un balanceador de carga, esto puede ocurrir cuando el nodo que sirve una solicitud no puede acceder a un archivo alojado que otro nodo creó, porque esos archivos son locales para cada nodo.

  • Solución:

    1. Confirma que los hosts de la puerta de enlace no se hayan quedado sin almacenamiento verificando el uso de disco e inodos (df -h y df -i). Libera espacio y prueba de nuevo 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 dirija 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 en contenedores, consulta Multi-gateway ALB: All containers must be on the same 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 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 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 con dependencias faltantes

  • Síntoma: Ejecutar yum install para instalar o actualizar una puerta de enlace privada de API Linux (RPM) a la versión 10.62 o posterior falla con 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 privada de API versión 10.62 y posterior 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 ese paso se omite, o cuando el host de la puerta de enlace no tiene acceso a internet y no puede alcanzar EPEL para descargar los paquetes.

  • Solución:

    • En un host de la puerta de enlace con acceso a internet, habilita el repositorio EPEL antes de instalar la puerta de enlace, tal como se describe en Install a private API gateway: ejecuta yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm, 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 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 privada de API devuelve:

    Failure, test call to API failed

  • Causa posible: En la versión 11.30 de la puerta de enlace privada de API y anteriores, la utilidad de autoprueba crea una API de prueba que carece de campos obligatorios (Service Name y Path), lo que causa que la llamada de prueba falle.

  • Solución:
    • Actualiza la puerta de enlace privada de API a la versión 11.31 o posterior, que lo resuelve automáticamente.
    • Si no es posible actualizar inmediatamente: abre la configuración de API para la API llamada ApiGatewayTest, completa el campo Service Name con cualquier valor (por ejemplo, service), establece Path 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 que coincidan

  • 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.
  • Posible causa: 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.
  • Posible causa: Las APIs 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 APIs de proxy, esta configuración predeterminada es true (reemplazo deshabilitado). Las APIs de proxy más antiguas pueden tenerla establecida en false, causando el reemplazo.
  • Resolución:
    • En la configuración de la 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 republica la API.

Los registros de operación no son visibles para operaciones desencadenadas 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.
  • Posible causa: Cuando una operación se activa 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 resultado de WriteToOperationLog de ejecuciones correctas se ocultan. Las ejecuciones correctas aparecen solo cuando Enable debug mode until (una configuración de API Manager) u Operation debug logging (una configuración de agente) está activo.
  • Resolución:
    1. Para ver registros de operación correctos y resultados de WriteToOperationLog, activa Enable debug mode until para la API en la pestaña de configuración de API, o habilita Operation debug logging en el agente.
    2. Para capturar también los datos brutos de solicitud y respuesta y las cargas útiles, activa Enable debug mode until (como en el paso 1), o combina Operation debug logging con Show Request & Response Payloads in Logs y Verbose logging. Los datos que captura cada configuración dependen de la combinación habilitada; para obtener 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 mantenerlo 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 solo está disponible 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 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 de registros de API retiene las selecciones de filtros anteriores

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

Las API no publicadas no aparecen en el menú desplegable de Análiticas

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

Límite de velocidad

Error 429: Se superó el subsidio mensual de visitas a API

  • Síntoma: Todas las API de la organización devuelven repentinamente errores HTTP 429.
  • Causa posible: La organización ha agotado su subsidio mensual de visitas a API según lo define su licencia. Cuando se supera el subsidio, todas las llamadas de API se rechazan con una respuesta 429 durante el resto del mes.
  • Resolución:
    • Verifica el recuento actual de visitas con tu subsidio mensual en la página de API. El subsidio se restablece 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 de Visitas por minuto para distribuir la carga e imponer límites de consumo por consumidor.
    • Para aumentar el subsidio mensual de tu organización, ponte en contacto con 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 correctamente.
  • Causa posible: El perfil de seguridad asignado a la API tiene grupos de IP de confianza configurados. Las solicitudes de direcciones IP fuera de los rangos permitidos se rechazan 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 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 APIs alojadas en la puerta de enlace API en la nube administrada por Jitterbit se limitan o se rechaza 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 API en la nube administrada por Jitterbit aplica un límite a nivel de plataforma de 200 solicitudes API por minuto por organización, compartido entre todos los tipos de API (personalizadas, proxy y OData). Este límite no se aplica a las puertas de enlace API privadas.
  • Resolución:
    • Revisa los patrones de tráfico de la API y distribuye las llamadas a lo largo del tiempo si es posible para mantenerse dentro del límite de 200 solicitudes por minuto.
    • Si el caso de uso requiere un rendimiento sostenido por encima de este límite, implementa una puerta de enlace 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 APIs aseguradas con TLS cuando se enrutan a través de una red Zscaler administrada 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 queda obsoleta e interrumpe la conexión nuevamente.
  • Resolución:
    • Instala el certificado de CA raíz de Zscaler en el almacén de confianza del SO o del navegador en los sistemas que realizan las llamadas a API, de modo que los certificados re-firmados por Zscaler sean de confianza.
    • 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 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 controlan correctamente.
    • No importes manualmente el certificado hoja de Jitterbit en un almacén de confianza como solución temporal: usa la CA raíz de Zscaler en su lugar para evitar problemas cuando Jitterbit renueva su certificado.