Ir para o conteúdo

Resolução de Problemas com APIs e Gerenciador de APIs

Este guia cobre erros e problemas comuns encontrados ao configurar, publicar e usar APIs no Jitterbit API Manager. Comece com os passos de diagnóstico abaixo para reunir informações e, em seguida, encontre seu problema específico na seção relevante.

Para uma referência unificada que abrange integração, automação, gerenciamento de APIs, EDI e problemas de desenvolvimento de aplicativos em um só lugar, consulte o guia de resolução de problemas do Harmony.

Todas as entradas de resolução de problemas nesta página

Etapas de diagnóstico

Essas etapas se aplicam à maioria dos problemas do Gerenciador de API e são o ponto de partida recomendado.

Verifique os logs da API

Revise os logs da API em busca de erros de solicitação e resposta relacionados à API afetada. Por padrão, os logs mostram metadados como códigos de status, mensagens de erro e timestamps, que podem ajudar a identificar a causa.

Para capturar também os payloads completos de solicitação e resposta, use o modo de depuração, a melhor opção para solução de problemas ativa: ele captura dados de solicitação e resposta juntamente com logs detalhados de nível de atividade, e desativa automaticamente na data que você definir.

  1. Na aba Configurações da configuração da API, ative Ativar modo de depuração até e defina uma data para mantê-lo ativo. Consulte a referência de configuração para APIs custom, OData ou proxy.
  2. Reproduza a solicitação e, em seguida, revise os payloads nos logs da API.

Nota

Para registrar payloads de forma contínua em vez de para uma janela fixa de solução de problemas, use Registro detalhado ou Mostrar Payloads de Solicitação e Resposta nos Logs para APIs custom e OData.

Verifique o status do sistema Jitterbit

Se um problema parecer afetar todas as APIs ou a interface do Gerenciador de API em vez de uma única API, verifique a página de status do sistema Jitterbit e a página de problemas conhecidos antes de investigar mais a fundo.

Falhas de autenticação e segurança

Microsoft Entra ID OAuth: O nome do perfil de segurança não pode conter espaços

  • Sintoma: Chamadas de API usando um Microsoft Entra ID (Azure AD) perfil de segurança OAuth 2.0 de três etapas falham com um erro da Microsoft indicando uma incompatibilidade na URL de resposta:

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

  • Causa possível: O nome do perfil de segurança contém espaços. Espaços no nome do perfil fazem com que a URI de redirecionamento OAuth seja construída incorretamente, o que não corresponde a nenhuma das URLs de resposta registradas no registro do aplicativo Azure.

  • Resolução:
    1. Abra o perfil de segurança no API Manager e renomeie-o para remover quaisquer espaços (por exemplo, mude Meu Perfil para MeuPerfil ou meu-perfil).
    2. No registro do aplicativo Azure, verifique se as URLs de resposta registradas lá correspondem à URI de redirecionamento que o API Manager gera para o perfil renomeado.

Microsoft Entra ID OAuth de 2 etapas: erro OAUTH_INVALID_TOKEN_CODE

  • Sintoma: Chamadas de API protegidas por um Microsoft Entra ID perfil de segurança OAuth 2.0 de duas etapas falham com:

    Failed to validate authentication token - HttpErrorResponse: OAUTH_INVALID_TOKEN_CODE

  • Causa possível: A reivindicação aud no JWT emitido pelo Entra ID não corresponde à audiência configurada no perfil de segurança do API Manager. Isso geralmente indica que o URI do ID do Aplicativo no registro do aplicativo Azure está mal configurado, ou o escopo OAuth que o cliente está solicitando não corresponde ao URI registrado.

  • Resolução:
    1. No portal Azure, abra o registro do aplicativo atribuído a este perfil de segurança e vá para Expor uma API.
    2. Confirme que o URI do ID do Aplicativo está definido como um URI válido no formato api://<ID do Aplicativo (cliente)>.
    3. No perfil de segurança, confirme que o Escopo OAuth está definido como api://<ID do Aplicativo (cliente)>/.default.
    4. Atualize o aplicativo cliente para solicitar um token usando este escopo exato.
    5. Se a validação ainda falhar após a audiência e o escopo estarem corretos, abra o manifesto do registro do aplicativo e confirme que requestedAccessTokenVersion está definido como 2. Um valor ausente ou diferente também pode causar a falha na validação do token.

A API do Azure AD Graph foi descontinuada

  • Sintoma: Chamadas de API que anteriormente funcionavam com um perfil de segurança do Microsoft Entra ID (Azure AD) falham com erros de autenticação.
  • Possível causa: O registro do aplicativo do perfil de segurança ainda está configurado para usar a API do Azure AD Graph, que foi descontinuada pela Microsoft em 30 de junho de 2025. Registros de aplicativos que não foram migrados para o Microsoft Graph falham ao fazer solicitações.
  • Resolução:
    1. No portal do Azure, migre o registro do aplicativo para Microsoft Graph.
    2. Após a migração, atualize o manifesto do aplicativo seguindo as etapas de permissões da API na configuração do perfil de segurança OAuth de 2 pernas do Microsoft Entra ID.

Provedor de identidade Google ou Salesforce: OAuth de 2 pernas não é suportado

  • Sintoma: Um perfil de segurança da API configurado com Google ou Salesforce como provedor de identidade OAuth 2.0 falha quando configurado para OAuth de 2 pernas.
  • Possível causa: Perfis de segurança da API OAuth 2.0 do Google e Salesforce não suportam OAuth de 2 pernas.
  • Resolução: Use um perfil de segurança OAuth 2.0 de 3 pernas para APIs que se autenticam com Google ou Salesforce como provedor de identidade.

Microsoft Copilot Studio: autenticação básica não suportada

  • Sintoma: Conectar uma API personalizada do Jitterbit ao Microsoft Copilot Studio (como uma ferramenta de API REST) falha quando o perfil de segurança da API usa autenticação básica.
  • Possível causa: O Microsoft Copilot Studio não suporta autenticação básica. Uma API personalizada do Jitterbit cujo perfil de segurança usa autenticação básica não pode ser chamada a partir do Copilot Studio.
  • Resolução:
    1. No API Manager, abra o perfil de segurança atribuído à API.
    2. Altere o tipo de autenticação para Chave da API ou OAuth 2.0, ou remova o perfil de segurança da API se o endpoint não exigir autenticação.
    3. Republique a API e, em seguida, reconecte-a no Microsoft Copilot Studio. Veja Conectar um agente de IA do Jitterbit ao Microsoft Copilot Studio.

"Botão Nova API" não visível apesar do papel correto na organização

  • Sintoma: O botão Nova API não aparece no API Manager para um usuário que possui um papel em nível de organização, mas não é um administrador da organização. Conceder ao usuário a permissão Admin em nível de organização faz o botão aparecer, mas também expõe todos os ambientes ao usuário.
  • Possível causa: Um papel em nível de organização por si só não é suficiente para criar APIs. O papel também deve ter acesso Gravar concedido em nível de ambiente para o ambiente específico onde precisam criar APIs.
  • Resolução:
    1. No Console de Gerenciamento, vá para Ambientes e abra o ambiente onde o usuário precisa criar APIs.
    2. Para o papel do usuário nesse ambiente, confirme se o acesso Gravar está habilitado. Se não estiver, habilite e salve.
    3. O botão Nova API agora deve estar visível para esse ambiente.
  • Sintoma: Uma API com dois ou mais Basic auth perfis de segurança atribuídos mostra nomes de usuário inesperados nos logs da API, incluindo nomes de usuário que não pertencem a nenhum dos perfis. Algumas requisições falham com um erro 401 Unauthorized.
  • Possível causa: O navegador ou cliente da API (como o Postman) armazenou credenciais de autenticação básica de uma sessão anterior como um cookie. Quando a API é chamada novamente, o cliente envia o cookie armazenado primeiro. Se as credenciais armazenadas não corresponderem a nenhum dos perfis de segurança configurados, a requisição é rejeitada e o nome de usuário inesperado aparece nos logs antes que a autenticação seja bem-sucedida com as credenciais corretas.

  • Resolução:

    1. Limpe os cookies e o cache do navegador, ou mude para uma janela de navegação anônima ou privada, antes de retestar a API.
    2. Confirme que o comportamento não está presente quando uma nova requisição é feita sem cookies de sessão anteriores. Se o erro desaparecer, o problema é o armazenamento em cache de credenciais do lado do cliente e não um problema de configuração.

    Note que qualquer cliente HTTP que armazena cookies (incluindo ferramentas baseadas em navegador e utilitários de teste de API) pode apresentar o mesmo comportamento.

401 Unauthorized com uma lista de IPs permitidos válida (cache obsoleto)

  • Sintoma: Chamadas de API retornam 401 Unauthorized mesmo que o IP do cliente esteja corretamente listado nos grupos de IPs confiáveis do perfil de segurança.
  • Possível causa: Um cache obsoleto de entradas de faixa de IPs legados no perfil de segurança está sobrepondo os grupos de IPs confiáveis ativos.
  • Resolução: Migre o perfil de segurança de faixas de IPs legados para o modelo de Grupos de IPs Confiáveis, o mecanismo atual de lista de permissões: defina os IPs como um grupo de IPs confiáveis e atribua-o ao perfil. Desativar a configuração Confiar apenas em requisições dos seguintes intervalos de IP em um perfil que ainda usa faixas de IPs legados remove permanentemente essas faixas (um aviso de confirmação alerta sobre isso), portanto, migre os IPs para um grupo de IPs confiáveis em vez de alternar a configuração para desativar o cache.

Publicação e implantação de API

Não é possível publicar uma API: Limite de API de assinatura alcançado

  • Sintoma: Criar ou publicar uma API falha com um erro como:

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

  • Causa: A organização atingiu o número máximo de URLs de API publicadas permitido pela sua assinatura. Cada API personalizada publicada, API OData ou API proxy (e cada uma de suas clones publicadas) utiliza uma URL de API; APIs em rascunho não contam.

  • Resolução: Na página APIs do Gerenciador de API, verifique as contagens de URLs de API personalizadas usadas e URLs de API proxy usadas, mostradas no topo da página, em relação aos totais permitidos pela sua assinatura. Despublique ou exclua APIs que não são mais necessárias para liberar URLs de API (APIs em rascunho não contam contra o limite). Para aumentar o limite, entre em contato com seu Gerente de Sucesso do Cliente.

API publicada retorna 404 Não Encontrado

  • Sintoma: Chamar uma API publicada retorna um erro 404.
  • Possíveis causas:
    • O limite de Hits por minuto no perfil de segurança atribuído está definido como zero, bloqueando todas as solicitações. Uma alteração no nível de assinatura da organização pode redefinir esse limite, fazendo com que uma API que anteriormente funcionava comece a retornar 404s.
    • A configuração da API, URL base ou configurações de visibilidade estão incorretas.
    • Um gateway de API privado não está reconhecendo a API após a implantação.
    • A API não foi totalmente publicada ou seus metadados estão incompletos.
  • Resolução:
    • Abra o perfil de segurança atribuído à API e confirme que o valor de Hits por minuto está definido como um número diferente de zero. Se o limite foi redefinido recentemente (por exemplo, após uma alteração de assinatura), restaure-o ao valor pretendido.
    • Na página de APIs, verifique se a API foi publicada com sucesso e se sua URL e configurações de visibilidade estão corretas.
    • Se a API for servida através de um gateway de API privado, verifique a instalação do gateway e a conectividade para quaisquer erros ou configurações incorretas.

URL do serviço excede o comprimento máximo (HTTP 414)

  • Sintoma: O gateway da API retorna:

    414 URI Too Large

  • Causa possível: A URL do serviço construída (incluindo a URL base, o caminho do serviço e quaisquer parâmetros de caminho ou consulta) excede 8.000 caracteres.

  • Resolução:
    • Reduza o comprimento da URL do serviço encurtando o caminho do serviço ou dividindo a API em vários endpoints.
    • Para APIs proxy, confirme que a combinação da URL base e todos os caminhos de serviço definidos permaneçam dentro do limite de 8.000 caracteres.

API Proxy: Parâmetros de caminho do serviço requerem um documento OpenAPI

  • Sintoma: Configurar um caminho de serviço de API proxy com parâmetros de caminho (por exemplo, /resource/{id}) falha quando inserido manualmente, porque o campo não aceita caracteres de colchete.
  • Causa possível: Caminhos de serviço definidos manualmente em APIs proxy não suportam os caracteres { e } usados para definir parâmetros de caminho.
  • Resolução: Para usar parâmetros de caminho em um caminho de serviço de API proxy, forneça um documento OpenAPI que define os caminhos e seus parâmetros. O Gerenciador de API descobre automaticamente os caminhos e seus parâmetros a partir da especificação OpenAPI, em vez de exigir que sejam inseridos manualmente.

Não é possível excluir uma API no Gerenciador de API

  • Sintoma: Excluir uma API no Gerenciador de API falha: a interface mostra um erro genérico e a API não é removida. A falha ocorre no navegador antes que qualquer solicitação de exclusão chegue ao servidor e aparece como um TypeError do JavaScript no console de desenvolvedor do navegador.
  • Causa possível: O papel do usuário não possui a permissão Admin. A exclusão de uma API primeiro verifica quais Grupos de API a API está associada, e visualizar a página Grupos de API requer a permissão Admin: um papel com apenas acesso Gravar ao ambiente pode abrir a página, mas não pode ler seu conteúdo. Quando o papel não pode ler os grupos de API, essa verificação recebe um valor que a interface não pode processar, e a exclusão não é concluída.
  • Resolução: Faça com que um usuário cujo papel tenha a permissão de papel Admin realize a exclusão. Conceder a permissão Admin ao papel afetado também funciona, mas isso é uma elevação ampla a nível organizacional, então prefira que um administrador existente exclua a API.

O ambiente da API não pode ser alterado após a criação

  • Sintoma: Uma API foi criada no ambiente errado e precisa ser movida, mas o campo do ambiente não é editável.
  • Causa possível: O ambiente é definido no momento da criação da API e não pode ser alterado posteriormente.
  • Solução:
    • Para mover uma API personalizada ou proxy para um ambiente diferente, clone a API a partir da página de APIs e selecione o ambiente correto durante o clone.
    • Alternativamente, exporte a API do seu ambiente atual e importe-a para o ambiente de destino.

CORS habilitado: requisições OPTIONS são executadas sem autenticação

  • Sintoma: Após habilitar CORS em uma API personalizada ou proxy, o método HTTP OPTIONS processa requisições sem autenticação.
  • Causa possível: Habilitar CORS faz com que operações usando o método OPTIONS sejam executadas sem autenticação. Isso é necessário para suportar requisições de pré-verificação do navegador, mas significa que qualquer requisição OPTIONS chega à operação sem passar pelo perfil de segurança.
  • Solução:
    • Se a API não usar OPTIONS para operações sensíveis, nenhuma ação é necessária. Esse é o comportamento esperado quando CORS está habilitado.
    • Se o tratamento autenticado de OPTIONS for necessário, desabilite CORS na API ou reestruture a operação para detectar e lidar com requisições de pré-verificação não autenticadas explicitamente.

Cloud proxy API: A API de destino deve ser acessível publicamente

  • Sintoma: Uma API proxy usando o gateway de API em nuvem hospedado pelo Jitterbit retorna erros ou não consegue acessar a API de destino.
  • Causa possível: Ao usar o gateway de API em nuvem, a API que está sendo proxy deve ser acessível a partir da internet pública. APIs atrás de um firewall ou em uma rede privada não podem ser acessadas pelo gateway em nuvem.
  • Resolução:
    • Confirme que a API de destino é acessível a partir da internet pública, mesmo que esteja protegida.
    • Se a API de destino deve permanecer atrás de um firewall, implante um gateway de API privado na mesma rede privada em vez de usar o gateway de API em nuvem.
    • Para permitir que os endereços IP do gateway em nuvem acessem a API proxy, consulte as informações de lista de permissão.

A configuração Mostrar Payloads de Solicitação e Resposta não tem efeito para APIs proxy

  • Sintoma: O botão Mostrar Payloads de Solicitação e Resposta nos Logs aparece nas configurações de uma API proxy, mas ativá-lo não tem efeito na saída do log.
  • Causa possível: O registro de payloads de solicitação e resposta não é suportado para APIs proxy. O botão é visível na interface de configuração, mas não funciona para este tipo de API.
  • Resolução: Para capturar payloads de solicitação e resposta, use uma API personalizada que chama o mesmo endpoint, onde a configuração Mostrar Payloads de Solicitação e Resposta nos Logs é suportada.

Desempenho e timeouts

HTTP 504 Timeout de Gateway

  • Sintoma: Chamadas de API retornam:

    504 Gateway Timeout

    Isso geralmente ocorre após o tempo limite do gateway (30 a 180 segundos, dependendo da configuração de Timeout da API).

  • Causas possíveis:

    • A URL da API está malformada ou os parâmetros de caminho não estão sendo tratados corretamente, fazendo com que o gateway falhe ao rotear a solicitação.
    • A operação de backend ou o serviço externo está muito lento para responder dentro do tempo limite do gateway, por exemplo, devido a cargas úteis grandes ou lógica de transformação complexa.
    • A solicitação não pode ser atribuída a um agente disponível, por exemplo, porque o grupo de agentes está com a concorrência máxima ou sob carga pesada, então ela expira no gateway antes que a operação seja executada. Um sinal desse caso é que a solicitação falhada não tem uma entrada correspondente nos logs da operação.

  • Resolução:

    • Verifique se a URL da API está corretamente formada. Se a API usar parâmetros de caminho, considere adicionar um script à operação que analise explicitamente a URL e capture os valores dos parâmetros.
    • Se o tempo limite for causado por um backend lento, revise a operação e sua lógica de transformação em busca de gargalos de desempenho, particularmente cargas de dados grandes ou chamadas externas lentas, e reduza o passo lento.
    • Se a operação realmente exigir mais tempo do que a configuração atual permite, aumente o tempo limite na aba de configurações da API. O tempo limite da API (padrão de 30 segundos, máximo de 180 segundos) é independente do tempo limite da operação do Studio; o tempo limite da operação é usado apenas em agentes privados quando a configuração EnableAPITimeout está habilitada na configuração do agente.
    • Se a operação não puder ser concluída dentro do tempo limite máximo, ou se uma resposta em tempo real não for necessária, redesenhe a operação da API para iniciar o trabalho de longa duração de forma assíncrona (por exemplo, chamando-a com RunOperation em modo assíncrono) para que a API possa retornar uma resposta sem esperar que ela termine. Veja Gerenciar operações assíncronas.
    • Para tempos limite intermitentes, adicione tentativas para que uma falha transitória seja reattemptada: use as configurações de tentativa integradas da conexão HTTP v2 para chamadas de saída, ou um loop de tentativa de RunOperation com um atraso entre as tentativas.
    • Se os tempos limite correlacionarem com a carga do agente, revise a capacidade do agente: execute operações que atendem à API em agentes separados de cargas de trabalho ETL pesadas e adicione agentes ao grupo se ele estiver saturado. Veja Otimizar e melhorar o desempenho dos agentes privados do Jitterbit.

O gateway privado retorna uma página 400 "verifique os Serviços Jitterbit" sem entrada de log da API

  • Sintoma: Solicitações através de um gateway de API privado falham intermitentemente com uma resposta HTTP 400. Em vez de uma resposta normal da API, o chamador recebe uma página de erro HTML semelhante 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.

    Nenhuma entrada aparece nos logs da API para a solicitação falhada, porque a solicitação nunca alcançou uma operação.

  • Causa possível: O grupo de agentes privado está sobrecarregado e não possui threads de trabalho Apache disponíveis para aceitar trabalhos do gateway de API privado. Quando nenhuma thread de trabalho está livre, a transferência do gateway para o agente falha com um reset de conexão antes que a solicitação possa ser registrada ou executada.

  • Resolução:
    1. Adicione mais agentes ao grupo de agentes para distribuir a carga e confirme se os hosts dos agentes têm CPU e memória suficientes.
    2. Monitore o uso das threads de trabalho Apache dos agentes. Se a observabilidade nativa estiver habilitada, revise os gráficos de Capacidade de Thread Apache, trabalhadores ociosos do Apache e trabalhadores ocupados do Apache (veja Painéis) para confirmar se as threads estão sendo esgotadas durante as falhas.
    3. Se os agentes constantemente ficarem sem threads de trabalho Apache mesmo após a escalabilidade, entre em contato com o suporte Jitterbit para revisar a capacidade de threads de trabalho Apache dos agentes (a configuração MaxRequestWorkers). Não altere os arquivos de configuração do Apache Jitterbit a menos que seja orientado pelo suporte Jitterbit. Veja arquivos de configuração do Apache.

Exibição e sincronização

O Portal da API não reflete as alterações do projeto

  • Sintoma: O Portal da API mostra nomes ou atributos de projeto desatualizados após um projeto ser renomeado ou atualizado.
  • Possível causa: O Portal da API não sincronizou automaticamente após a alteração do projeto.
  • Resolução:
    1. Para atualizar todas as APIs personalizadas e de proxy no ambiente, abra o Gerenciador do Portal e clique em Regenerar Docs. Para atualizar uma única API, abra a aba Documentação na página de APIs e clique em Salvar & Publicar.
    2. Verifique se as informações atualizadas estão refletidas corretamente no Portal da API.

Alterações no perfil de segurança levam vários minutos para ter efeito

  • Sintoma: Uma API continua se comportando como se uma configuração antiga de perfil de segurança estivesse ativa, mesmo após o perfil ter sido atualizado e salvo.
  • Possível causa: Perfis de segurança são armazenados em cache no gateway da API. Alterações em um perfil de segurança ativo não têm efeito imediato.
  • Resolução:
    1. Aguarde vários minutos após salvar uma alteração no perfil de segurança antes de testar a API afetada.
    2. Se o problema persistir após 10 minutos, confirme se a alteração foi salva corretamente reabrindo o perfil de segurança.

Excluir uma API não atualiza a documentação do Portal da API

  • Sintoma: Após excluir uma API, sua documentação OpenAPI permanece visível no Portal da API.
  • Possível causa: A documentação do Portal da API não é atualizada automaticamente quando uma API é excluída do Gerenciador de API.
  • Resolução:
    • Após excluir uma API, abra o Gerenciador do Portal e remova ou atualize manualmente a entrada de documentação da API lá.
    • Alternativamente, use a aba Documentação para a API antes de excluí-la para remover a entrada do Portal primeiro.

O perfil de segurança não pode ser excluído enquanto ainda estiver atribuído a uma API publicada

  • Sintoma: Tentar excluir um perfil de segurança falha ou a opção de exclusão não está disponível, mesmo após desatribuir o perfil de uma API.
  • Causa possível: Após remover um perfil de segurança da configuração de uma API, a API deve ser salva e republicada antes que o perfil seja considerado totalmente desatribuído. Até que a API seja republicada, o Gerenciador de API ainda trata o perfil como em uso.
  • Resolução:
    1. Após desatribuir o perfil de segurança da API, clique em Salvar e depois Publicar a API.
    2. Uma vez que a API tenha sido republicada com a configuração atualizada, o perfil de segurança não mostrará mais como em uso e poderá ser excluído.

Problemas com gateway privado

OAuth de 2 pernas reverte para 3 pernas em versões de gateway privado anteriores a 10.48

  • Sintoma: Um perfil de segurança configurado para OAuth de 2 pernas usa OAuth de 3 pernas em vez disso quando servido através de um gateway de API privado.
  • Causa possível: Gateways de API privados anteriores à versão 10.48 não suportam OAuth de 2 pernas. Se a versão do gateway estiver abaixo de 10.48, o perfil de segurança reverte para OAuth de 3 pernas, mesmo quando OAuth de 2 pernas está configurado.
  • Resolução:
    1. Verifique a versão do gateway de API privado que serve a API.
    2. Atualize o gateway para a versão 10.48 ou posterior para habilitar o suporte a OAuth de 2 pernas.

ALB de múltiplos gateways: Todos os contêineres devem estar no mesmo host

  • Sintoma: Em um ambiente multi-gateway containerizado atrás de um balanceador de carga de aplicativo (ALB), chamadas de API falham intermitentemente ou cargas úteis não podem ser recuperadas, mesmo que gateways individuais pareçam saudáveis.
  • Possível causa: Ao usar um gateway de API privado containerizado com um ALB, todos os containers de gateway devem ser executados na mesma máquina host. Containers implantados em diferentes hosts não conseguem coordenar a recuperação de cargas úteis, causando falhas intermitentes.
  • Resolução:
    1. Confirme que todos os containers de gateway de API privado no grupo estão sendo executados no mesmo host físico ou virtual.
    2. Se os containers estiverem espalhados por vários hosts, consolide-os em um único host.
    3. Para implantações em múltiplos hosts, revise a configuração do ALB no guia de instalação do gateway para requisitos adicionais de configuração.

Gateway privado: A configuração SSL personalizada é sobrescrita por atualizações

  • Sintoma: Após atualizar um gateway de API privado, as configurações de protocolo ou cifra SSL personalizadas não são mais aplicadas e o gateway reverte ao comportamento padrão do TLS.
  • Possível causa: O processo de atualização do gateway de API privado sobrescreve o arquivo de configuração local (/usr/local/openresty/nginx/conf/onpremise.conf). Quaisquer alterações manuais a este arquivo, incluindo restrições de protocolo SSL personalizadas ou listas de cifras, são perdidas durante a atualização.
  • Resolução:
    1. Antes de atualizar o gateway de API privado, faça um backup do arquivo de configuração local.
    2. Após a conclusão da atualização, reaplique suas configurações SSL personalizadas ao novo arquivo de configuração.

Gateway privado retorna HTTP 507 ou "Arquivo ou diretório não encontrado"

  • Sintoma: Os endpoints do gateway API privado retornam 507 Insufficient Storage. Os logs do gateway mostram:

    could not open payload file: No such file or directory

    mesmo quando há espaço em disco suficiente nos hosts do gateway.

  • Causa possível: Aqui, 507 significa que o gateway não conseguiu abrir o arquivo de payload ou resposta hospedado para a solicitação; isso não significa necessariamente que o host está sem armazenamento. Em um gateway API privado de múltiplos nós atrás de um balanceador de carga, isso pode acontecer quando o nó que atende a uma solicitação não consegue acessar um arquivo hospedado que outro nó criou, porque esses arquivos são locais a cada nó.

  • Resolução:

    1. Confirme que os hosts do gateway não estão realmente sem armazenamento verificando o uso de disco e inode (df -h e df -i). Libere espaço e reteste apenas se eles estiverem realmente cheios.
    2. Se o gateway estiver rodando como múltiplos nós atrás de um balanceador de carga, confirme que o balanceador de carga roteia cada solicitação e sua resposta consistentemente para o mesmo nó, porque os arquivos de payload e resposta hospedados são locais ao nó que os criou. Para gateways conteinerizados, veja Multi-gateway ALB: Todos os contêineres devem estar no mesmo host.
    3. Se o erro persistir, ative o registro de rastreamento no gateway (defina traceLogsEnabled como true na configuração do gateway) e entre em contato com o suporte da Jitterbit com os logs de rastreamento resultantes, os logs do gateway (/opt/jitterbit/var/log/api-gateway), os logs do NGINX ou OpenResty, e a saída de ls -lR para os diretórios hosted-files em cada nó. O suporte pode verificar condições do lado do servidor que não são configuráveis pelo cliente, como o mapeamento host-para-ambiente, entradas de domínio privado obsoletas e permissões de arquivo.

A instalação ou atualização do gateway privado falha devido a dependências ausentes

  • Sintoma: Executar yum install para instalar ou atualizar um gateway API privado Linux (RPM) para a versão 10.62 ou posterior falha com erros de dependência ausente:

    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 possível: A versão 10.62 e posteriores do gateway de API privado requerem os pacotes geoip-devel e libGeoIP, que são fornecidos pelo repositório EPEL. A instalação documentada habilita o EPEL antes de instalar o gateway. O erro ocorre quando essa etapa é pulada ou quando o host do gateway não tem acesso à internet e não consegue acessar o EPEL para baixar os pacotes.

  • Resolução:

    • Em um host de gateway com acesso à internet, habilite o repositório EPEL antes de instalar o gateway, conforme descrito em Instalar um gateway de API privado: execute yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm, em seguida, execute novamente a instalação do gateway.
    • Em um host isolado sem acesso à internet, instalar apenas o pacote epel-release adiciona apenas a definição do repositório; não baixa os pacotes geoip-devel e libGeoIP. Em uma máquina com acesso à internet, baixe esses pacotes e suas dependências transitivas, transfira-os para o host do gateway e instale-os na ordem de dependência com yum install <package.rpm> antes de executar novamente a instalação do gateway.

O auto-teste do gateway privado retorna "Falha, chamada de teste para a API falhou"

  • Sintoma: A ferramenta de auto-teste de linha de comando do gateway de API privado retorna:

    Failure, test call to API failed

  • Causa possível: Nas versões 11.30 e anteriores do gateway de API privado, a ferramenta de auto-teste cria uma API de teste que está faltando campos obrigatórios (Nome do Serviço e Caminho), fazendo com que a chamada de teste falhe.

  • Resolução:
    • Atualize o gateway de API privado para a versão 11.31 ou posterior, o que resolve isso automaticamente.
    • Se a atualização imediata não for possível: abra a configuração da API para a API chamada ApiGatewayTest, preencha o campo Nome do Serviço com qualquer valor (por exemplo, serviço), defina Caminho como /, salve e publique, em seguida, execute novamente a ferramenta de auto-teste.

Análise e comportamento da API

OData $count ou $inlinecount retorna um erro quando nenhum registro corresponde

  • Sintoma: Uma consulta de API OData usando as opções de consulta do sistema $count ou $inlinecount retorna um erro em vez de 0 quando nenhum registro corresponde ao filtro.
  • Causa possível: Por padrão, uma API OData retorna um erro em vez de 0 quando uma consulta $count ou $inlinecount não corresponde a nenhum registro.
  • Solução: Em agentes privados executando a versão 11.32 ou posterior, defina o parâmetro OData $noErrorOnZeroCount como true na configuração da API OData. Isso faz com que consultas $count retornem 0 em vez de um erro quando nenhum registro corresponde.

API Proxy: Hífens no cabeçalho da solicitação substituídos por sublinhados

  • Sintoma: Uma operação de API proxy recebe cabeçalhos de solicitação com hífens substituídos por sublinhados (por exemplo, X-Custom-Header chega como X_Custom_Header), causando falhas nas buscas de cabeçalho.
  • Causa possível: As APIs proxy têm uma configuração disable-hyphen-replacement que controla se os hífens nos nomes dos cabeçalhos de solicitação são substituídos por sublinhados. Para novas APIs proxy, essa configuração é, por padrão, true (substituição desativada). APIs proxy mais antigas podem ter essa configuração definida como false, causando a substituição.
  • Solução:
    • Na configuração da API proxy, verifique a configuração do cabeçalho disable-hyphen-replacement. Para preservar os hífens nos nomes dos cabeçalhos, certifique-se de que a configuração esteja como true.
    • Se a API proxy foi criada antes que esse padrão fosse introduzido e a substituição estiver ocorrendo inesperadamente, atualize a configuração para true e republicar a API.

Os logs de operação não são visíveis para operações acionadas por API quando o modo de depuração está desativado

  • Sintoma: Após chamar uma API, o log da API mostra que a chamada foi executada com sucesso, mas nenhum log de operação aparece na página Runtime para a operação que a API acionou. Chamadas para WriteToOperationLog de dentro da operação também não produzem entradas de log visíveis.
  • Causa possível: Quando uma operação é acionada através de uma API publicada, execuções bem-sucedidas não aparecem nos logs de operação por padrão. Operações malsucedidas são sempre registradas; apenas logs de operações bem-sucedidas e qualquer saída de WriteToOperationLog de execuções bem-sucedidas são ocultados. Execuções bem-sucedidas aparecem apenas quando Ativar modo de depuração até (uma configuração do API Manager) ou Registro de depuração da operação (uma configuração do agente) está ativo.
  • Resolução:
    1. Para ver logs de operação bem-sucedidos e saída de WriteToOperationLog, ative Ativar modo de depuração até para a API na aba de configurações da API, ou ative Registro de depuração da operação no agente.
    2. Para capturar também os dados e cargas úteis de solicitação e resposta brutos, ative Ativar modo de depuração até (como no passo 1), ou combine Registro de depuração da operação com Mostrar cargas úteis de solicitação e resposta nos logs e Registro detalhado. Quais dados cada configuração captura depende da combinação ativada; para a divisão completa, consulte Dados de solicitação e resposta da API.
    3. Desative o modo de depuração após coletar os logs necessários, pois deixá-lo ativado aumenta o volume de logs.

API payload disponível no agente por 2 dias

  • Sintoma: Um fluxo de trabalho que recupera um payload de solicitação de API do agente mais de 2 dias após a chamada da API não consegue encontrar o payload.
  • Possível causa: Payloads de solicitação de API para APIs personalizadas e APIs OData são armazenados no agente por um máximo de 2 dias. Após esse período, o payload está disponível apenas se a operação já o tiver gravado em um conector de armazenamento persistente (como Armazenamento Temporário, Compartilhamento de Arquivos ou um banco de dados).
  • Resolução:
    • Projete operações que consomem payloads de solicitação de API para processar os dados imediatamente quando a API é chamada, em vez de adiar a recuperação do payload.
    • Se o payload precisar ser retido por um processamento mais longo, grave-o em um local de armazenamento persistente na operação inicial acionada pela API.

A página de Logs da API retém seleções de filtro anteriores

  • Sintoma: A página de Logs da API não está mostrando as entradas de log esperadas, mesmo que a API esteja sendo executada com sucesso.
  • Possível causa: A página Logs da API lembra as seleções de filtro da sessão anterior. Um filtro aplicado anteriormente pode estar ocultando os resultados esperados.
  • Resolução: Na página Logs da API, revise todos os filtros ativos e limpe qualquer um que possa estar excluindo as entradas esperadas.

APIs não publicadas não aparecem no dropdown de APIs de Análise

  • Sintoma: Uma API não aparece no dropdown de APIs na página de Análise, portanto, os dados analíticos para essa API não podem ser filtrados.
  • Possível causa: Apenas APIs atualmente publicadas aparecem no dropdown de APIs. APIs que foram despublicadas são excluídas do dropdown, mesmo que existam logs de API para essas APIs.
  • Resolução:
    • Confirme se a API foi publicada. Para visualizar dados analíticos, a API deve estar em um estado publicado.
    • Para visualizar entradas de log de uma API não publicada, use a página de Logs da API em vez disso. Os dados de log permanecem disponíveis lá, mas não podem ser filtrados pelo nome da API.

Limitação de taxa

Erro 429: Limite mensal de chamadas de API excedido

  • Sintoma: Todas as APIs na organização retornam repentinamente erros HTTP 429.
  • Causa possível: A organização esgotou seu limite mensal de chamadas de API conforme definido pela sua licença. Quando o limite é excedido, todas as chamadas de API são rejeitadas com uma resposta 429 pelo restante do mês.
  • Resolução:
    • Verifique a contagem atual de chamadas em relação ao seu limite mensal na página de APIs. O limite é redefinido no primeiro dia do mês seguinte.
    • Para evitar atingir o limite, configure limites de taxa no nível do ambiente ou do perfil de segurança usando a configuração Chamadas por minuto para distribuir a carga e impor limites de consumo por consumidor.
    • Para aumentar o limite mensal da sua organização, entre em contato com seu Gerente de Sucesso do Cliente.

Erro 429: IP do consumidor não está na faixa de IPs confiáveis

  • Sintoma: Um consumidor ou aplicativo específico recebe erros HTTP 429 ao chamar uma API, enquanto outros consumidores conseguem chamar a mesma API com sucesso.
  • Causa possível: O perfil de segurança atribuído à API possui grupos de IPs confiáveis configurados. Solicitações de endereços IP fora das faixas permitidas são rejeitadas com uma resposta 429.
  • Resolução:
    1. Abra o perfil de segurança atribuído à API e revise a configuração do grupo de IPs confiáveis.
    2. Adicione o endereço IP ou a faixa de endereços do consumidor a um grupo de IPs confiáveis existente, ou crie um novo grupo de IPs confiáveis que inclua os endereços necessários.

Limite de taxa em nível de plataforma: 200 solicitações por minuto

  • Sintoma: APIs hospedadas no gateway de API gerenciado pela Jitterbit são limitadas ou rejeitadas com uma resposta 429 Too Many Requests sob alta carga, mesmo quando os limites de taxa do perfil de segurança não foram alcançados.
  • Possível causa: O gateway de API gerenciado pela Jitterbit impõe um limite em nível de plataforma de 200 solicitações de API por minuto por organização, compartilhado entre todos os tipos de API (personalizadas, proxy e OData). Este limite não se aplica a gateways de API privados.
  • Resolução:
    • Revise seus padrões de tráfego de API e distribua chamadas ao longo do tempo, se possível, para permanecer dentro do limite de 200 solicitações por minuto.
    • Se seu caso de uso exigir um throughput sustentado acima desse limite, implante um gateway de API privado onde o throughput é determinado pela capacidade do servidor host, em vez de um limite em nível de plataforma.

Rede e conectividade

Zscaler ou firewall que intercepta SSL bloqueia o acesso à API

  • Sintoma: Chamadas de API falham com erros de certificado, ou endpoints de backend não conseguem acessar APIs protegidas com TLS quando roteadas através de uma rede gerenciada pelo Zscaler ou similar que inspeciona SSL.
  • Possíveis causas:
    • Zscaler e proxies de segurança similares realizam inspeção SSL/TLS interceptando o tráfego HTTPS e re-assinando-o com seu próprio certificado CA. Sistemas clientes que não confiam na CA raiz do Zscaler rejeitam a conexão.
    • Importar manualmente o certificado da Jitterbit para o armazenamento de confiança não é uma solução confiável: quando a Jitterbit renova seu certificado, a cópia importada manualmente se torna obsoleta e quebra a conexão novamente.
  • Resolução:
    • Instale o certificado CA raiz do Zscaler no armazenamento de confiança do sistema operacional ou navegador nos sistemas que fazem as chamadas de API, para que os certificados re-assinados pelo Zscaler sejam confiáveis.
    • Para ferramentas como curl, wget ou openssl, configure-as para usar o proxy HTTP definido no ambiente do Zscaler.
    • Solicite uma exceção de política do Zscaler para os nomes de host do gateway de API Jitterbit para contornar a inspeção SSL para esses destinos específicos.
    • Revise as regras do arquivo PAC (proxy auto-configuração) da organização para confirmar que os endpoints da Jitterbit estão sendo tratados corretamente.
    • Não importe manualmente o certificado leaf da Jitterbit para um armazenamento de confiança como uma solução alternativa: use a CA raiz do Zscaler em vez disso para evitar quebras quando a Jitterbit renova seu certificado.