Ir para o conteúdo

Solução de problemas com APIs e API Manager

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

Para uma referência unificada que abrange problemas de integração, automação, gerenciamento de API, EDI e desenvolvimento de aplicativos em um único lugar, consulte o guia de solução de problemas do Harmony.

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

Etapas de diagnóstico

Essas etapas se aplicam à maioria dos problemas do API Manager e representam o ponto de partida recomendado.

Verificar os logs da API

Revise os logs da API para erros de requisição e resposta relacionados à API afetada. Por padrão, os logs exibem metadados como códigos de status, mensagens de erro e timestamps, o que pode ajudar a estreitar as possíveis causas.

Para também capturar os payloads completos de requisição e resposta, use o modo de depuração, a melhor opção para troubleshooting ativo: ele captura dados de requisição e resposta junto com logging detalhado em nível de atividade, e desativa automaticamente na data que você definir.

  1. Na guia 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 personalizadas, serviços OData ou APIs proxy.
  2. Reproduza a requisição e, em seguida, revise os payloads nos logs da API.

Nota

Para fazer login de payloads de forma contínua em vez de em uma janela de troubleshooting fixa, use Registro detalhado ou Mostrar payloads de requisição e resposta nos logs para serviços personalizados e OData.

Verificar o status do sistema Jitterbit

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

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 à API usando um perfil de segurança OAuth 2.0 de três etapas do Microsoft Entra ID (Azure AD) falham com um erro do Microsoft indicando uma incompatibilidade de URL de resposta:

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

  • Possível causa: 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 de aplicativo do Azure.

  • Resolução:
    1. Abra o perfil de segurança no API Manager e renomeie-o para remover espaços (por exemplo, altere My Profile para MyProfile ou my-profile).
    2. No registro de aplicativo do 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 duas etapas: erro OAUTH_INVALID_TOKEN_CODE

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

    Failed to validate authentication token - HttpErrorResponse: OAUTH_INVALID_TOKEN_CODE

  • Possível causa: A declaração aud no JWT emitido pela Entra ID não corresponde ao público-alvo configurado no perfil de segurança do API Manager. Isso geralmente indica que a URI de ID do Aplicativo no registro do aplicativo do Azure está configurada incorretamente, ou o escopo OAuth que o cliente está solicitando não corresponde à URI registrada.

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

Azure AD Graph API foi descontinuado

  • Sintoma: Chamadas de API que funcionavam anteriormente 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 Azure AD Graph API, que a Microsoft descontinuou em 30 de junho de 2025. Os registros de aplicativo 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 de 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 de API configurado com Google ou Salesforce como provedor de identidade OAuth 2.0 falha quando configurado para OAuth de 2 pernas.
  • Possível causa: Os perfis de segurança de 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 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 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 de 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 reconecte-a no Microsoft Copilot Studio. Veja Conectar um agente Jitterbit AI ao Microsoft Copilot Studio.

Botão "Nova API" não visível apesar da função de organização correta

  • Sintoma: O botão Nova API não aparece no API Manager para um usuário que possui uma função no nível da organização, mas não é administrador da organização. Conceder permissão de Admin ao usuário no nível da organização faz o botão aparecer, mas também expõe todos os ambientes para o usuário.
  • Possível causa: Uma função no nível da organização por si só não é suficiente para criar APIs. A função também deve ter acesso de Gravação concedido no nível do ambiente para o ambiente específico onde precisam criar APIs.
  • Resolução:
    1. No Console de Gerenciamento, acesse Ambientes e abra o ambiente onde o usuário precisa criar APIs.
    2. Para a função do usuário nesse ambiente, confirme que o acesso de Gravação está habilitado. Se não estiver, habilite-o e salve.
    3. O botão Nova API agora deve estar visível para esse ambiente.

  • Sintoma: Uma credencial de autenticação básica armazenada em cache de uma solicitação anterior pode afetar uma chamada de API posterior de uma destas formas:

    • Uma API com dois ou mais perfis de segurança de autenticação Básica atribuídos mostra nomes de usuário inesperados nos logs de API, incluindo nomes de usuário que não pertencem a nenhum dos perfis. Algumas solicitações falham com um erro 401 Não autorizado.
    • Uma API proxy ou serviço OData com um perfil de segurança de autenticação Básica atribuído retorna uma resposta bem-sucedida sem solicitar credenciais.

  • Possível causa: O navegador ou cliente de API (como Postman) armazenou em cache as 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 em cache primeiro. Se as credenciais em cache não corresponderem a nenhum perfil de segurança atribuído, a solicitação é rejeitada e o nome de usuário inesperado aparece nos logs antes da autenticação ter sucesso com as credenciais corretas. Se corresponderem, a solicitação tem sucesso sem um novo aviso.

  • 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 testar a API novamente.
    2. Confirme que o comportamento não está presente quando uma solicitação nova é feita sem cookies de sessão anterior. Se o comportamento desaparecer, trata-se de armazenamento em cache de credenciais no lado do cliente e não de um problema de configuração.

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

Erro INVALID_TRIGGER_USER ou TRIGGER_USER_TOO_LONG

  • Sintoma: Uma chamada de API usando um perfil de segurança com autenticação básica ou uma configuração de Personalizado de Logging falha com um erro INVALID_TRIGGER_USER ou TRIGGER_USER_TOO_LONG, mesmo que as mesmas credenciais ou valor de cabeçalho tenham funcionado anteriormente.

  • Possível causa: O valor usado para identificar o chamador da solicitação viola uma regra de validação: contém um caractere não permitido (INVALID_TRIGGER_USER) ou excede 256 caracteres (TRIGGER_USER_TOO_LONG).

A validação de caracteres foi adicionada na versão 12.10 do Harmony, e o limite de comprimento foi adicionado na versão 12.11 do Harmony. Um gateway de API privado executando uma versão anterior não aplica a validação correspondente, portanto qualquer um dos erros pode aparecer pela primeira vez após a atualização do gateway, mesmo que a configuração do perfil de segurança não tenha mudado.

A partir da versão 12.12 do Harmony, o campo Nome de usuário do perfil de segurança rejeita os caracteres não permitidos, então não é mais possível salvar um perfil de segurança que os contenha. Para autenticação Basic com a configuração padrão de Logging, o erro INVALID_TRIGGER_USER se aplica apenas aos perfis de segurança salvos antes dessa versão.

  • Resolução:
    • Para autenticação Basic com a configuração padrão de Logging, edite o campo Nome de usuário do perfil de segurança para remover os caracteres não permitidos ou reduzi-lo para 256 caracteres ou menos, conforme aplicável, e depois atualize as credenciais em qualquer aplicação chamadora que referencia o nome de usuário anterior.
    • Para uma configuração Custom de Logging, atualize a aplicação chamadora para enviar um valor de header que não contenha caracteres não permitidos e tenha 256 caracteres ou menos.

401 Unauthorized com uma lista de permissões de IP válida (cache obsoleto)

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

Salesforce no Hyperforce: Chamadas para uma API são rejeitadas após mudança de endereços IP do Salesforce

  • Sintoma: Chamadas do Salesforce para uma API (mensagens de saída, chamadas Apex, Salesforce Connect ou ações invocáveis) são rejeitadas após a org do Salesforce migrar para o Hyperforce, a infraestrutura de nuvem pública do Salesforce. O perfil de segurança da API tem Confiar apenas em solicitações dos seguintes intervalos de IP ativado com um grupo de IP confiável que lista os endereços IP do Salesforce.

  • Possível causa: Grupos de IP confiáveis correspondem ao endereço IP de origem de uma solicitação, e os endereços que uma org do Salesforce no Hyperforce usa para chamadas de saída mudam ao longo do tempo. Um grupo listando um conjunto fixo de endereços do Salesforce deixa de corresponder.

  • Resolução: O Salesforce recomenda autenticar chamadas em sua rede em vez de permitir seus endereços IP de origem:

    1. Abra o perfil de segurança atribuído à API e defina seu Tipo de autenticação como Chave de API. Configure a chamada do Salesforce para enviar a chave em um header de solicitação, não em um parâmetro de query, para que não seja registrada em URLs de solicitação. OAuth 2.0 também está disponível, mas com o Salesforce como provedor de identidade o único fluxo é 3-legged, que requer interação manual.

  • Após a chamada ser autenticada com sucesso, desatribua o grupo de IP confiável que lista os endereços do Salesforce, para que as alterações de endereço posteriores não afetem mais a API. Desatribua o grupo em vez de desativar Confiar em solicitações apenas dos seguintes intervalos de IP, que remove permanentemente qualquer intervalo de IP herdado ainda mantido no perfil.

    Se sua organização exigir lista de permissões de IP, o Salesforce publica seus intervalos de Hyperforce como uma lista dinâmica em ip-ranges.salesforce.com/ip-ranges.json, anunciando adições antecipadamente. Essa lista muda sempre que o Salesforce altera seus endereços, portanto, manter uma lista de permissões atualizada significa rastrear o arquivo e atualizar o grupo de IP confiável para corresponder a ele. As chamadas de um endereço adicionado desde a última atualização do grupo são rejeitadas. Esses endereços também são compartilhados entre organizações do Salesforce, portanto, a lista de permissões deles confirma de onde veio uma solicitação, não que veio de sua organização. Para obter as orientações completas do Salesforce, incluindo SSL bidirecional (mTLS), Provedores de Autenticação e aplicativos conectados, consulte Manter acesso ininterrupto aos serviços do Salesforce no Hyperforce.

Publicação e implantação de API

Não é possível publicar uma API: limite de API de assinatura atingido

  • Sintoma: A criação ou publicação de 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 permitidas por sua assinatura. Cada API personalizada publicada, serviço OData ou API proxy (e cada um de seus clones publicados) usa uma URL de API; APIs de rascunho não contam.

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

API publicada retorna erro 404 Not Found

  • 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 é definido como zero, bloqueando todas as solicitações. Uma alteração no nível de assinatura da organização pode redefinir esse limite, portanto, uma API que funcionava anteriormente pode começar a retornar 404s.
    • A configuração da API, URL base ou configurações de visibilidade estão incorretas.
    • Um gateway de API privada 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 para o 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 por um gateway de API privada, verifique a instalação do gateway e a conectividade para qualquer erro ou configuração incorreta.

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

  • Sintoma: O gateway de API retorna:

    414 URI Too Large

  • Possível causa: A URL do serviço construída (incluindo URL base, 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 de proxy, confirme que a combinação da URL base e todos os caminhos de serviço definidos fica dentro do limite de 8.000 caracteres.

API de proxy: parâmetros de caminho de serviço exigem um documento OpenAPI

  • Sintoma: A configuração de um caminho de serviço de API de proxy com parâmetros de caminho (por exemplo, /resource/{id}) falha quando inserida manualmente, pois o campo não aceita caracteres de chave.
  • Possível causa: Caminhos de serviço definidos manualmente em APIs de proxy não oferecem suporte aos 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 de proxy, forneça um documento OpenAPI que defina os caminhos e seus parâmetros. O API Manager descobre automaticamente os caminhos e seus parâmetros da especificação OpenAPI em vez de exigir que sejam inseridos manualmente.

Não é possível excluir uma API no API Manager

  • Sintoma: A exclusão de uma API no API Manager falha: a interface mostra um erro genérico e a API não é removida. A falha ocorre no navegador antes de qualquer solicitação de exclusão chegar ao servidor e aparece como um TypeError de JavaScript no console do desenvolvedor do navegador.
  • Possível causa: A função 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: uma função com apenas acesso ao ambiente Write pode abrir a página, mas não pode ler seu conteúdo. Quando a função não consegue ler os grupos de API, essa verificação recebe um valor que a interface não consegue processar, e a exclusão não é concluída.
  • Resolução: Tenha um usuário cuja função possua a permissão permissão de função Admin execute a exclusão. Conceder a permissão Admin à função afetada também funciona, mas representa uma elevação ampla no nível da organização, então prefira ter um administrador existente excluir 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 de ambiente não é editável.
  • Possível causa: O ambiente é definido no momento da criação da API e não pode ser alterado posteriormente.
  • Resolução:
    • Para mover uma API personalizada ou de proxy para um ambiente diferente, clone a API na página APIs e selecione o ambiente correto durante a clonagem.
    • Como alternativa, exporte a API de 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 de proxy, o método HTTP OPTIONS processa requisições sem autenticação.
  • Possível causa: 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 preflight do navegador, mas significa que qualquer requisição OPTIONS chega à operação sem passar pelo perfil de segurança.
  • Resolução:
    • Se a API não usa OPTIONS para operações sensíveis, nenhuma ação é necessária. Esse é o comportamento esperado quando CORS está habilitado.
    • Se for necessário o tratamento autenticado de OPTIONS, desabilite CORS na API ou reestruture a operação para detectar e tratar explicitamente requisições de preflight não autenticadas.

API proxy em nuvem: a API de destino deve estar acessível publicamente

  • Sintoma: uma API proxy que usa o gateway de API em nuvem hospedado pelo Jitterbit retorna erros ou não consegue acessar a API de destino.
  • Possível causa: ao usar o gateway de API em nuvem, a API sendo proxificada deve estar acessível pela internet pública. APIs atrás de um firewall ou em uma rede privada não podem ser alcançadas pelo gateway em nuvem.
  • Resolução:
    • Confirme que a API de destino está acessível pela internet pública, mesmo que esteja protegida.
    • Se a API de destino precisar 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 colocar na lista de permissões os endereços IP do gateway em nuvem e permitir que o gateway acesse a API proxificada, consulte Informações de lista de permissões.

A configuração Exibir Cargas de Solicitação e Resposta não tem efeito para APIs proxy

  • Sintoma: a opção Exibir Cargas de Solicitação e Resposta em Logs aparece nas configurações de uma API proxy, mas ativá-la não tem efeito na saída de logs.
  • Possível causa: o registro em log de carga de solicitação e resposta não é suportado para APIs proxy. A opção fica visível na interface de configuração, mas não funciona para este tipo de API.
  • Resolução: para capturar cargas de solicitação e resposta, use uma API personalizada que chama o mesmo endpoint, onde a configuração Exibir Cargas de Solicitação e Resposta em Logs é suportada.

Desempenho e timeouts

HTTP 504 Gateway Timeout

  • Sintoma: chamadas de API retornam:

    504 Gateway Timeout

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

  • Possíveis causas:

    • 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 serviço externo é muito lento para responder na janela de timeout do gateway, por exemplo, por causa de 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 concorrência total ou sob carga pesada, portanto, expira no gateway antes da operação ser executada. Um sinal deste caso é que a solicitação falhada não tem entrada correspondente nos logs de operação.

  • Resolução:

    • Verifique se a URL da API está formada corretamente. Se a API usa parâmetros de caminho, considere adicionar um script à operação que analisa explicitamente a URL e captura os valores dos parâmetros.
    • Se o timeout é causado por um backend lento, revise a operação e sua lógica de transformação para encontrar gargalos de desempenho, particularmente cargas de dados grandes ou chamadas externas lentas, e reduza a etapa lenta.
    • Se a operação genuinamente requer mais tempo do que a configuração atual permite, aumente o timeout na guia de configurações da API. O timeout da API (padrão 30 segundos, máximo 180 segundos) é independente do timeout da operação do Studio; o timeout 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 conseguir ser concluída no timeout máximo, ou uma resposta em tempo real não for necessária, reformule 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), de modo que a API possa retornar uma resposta sem esperar sua conclusão. Consulte Gerenciar operações assíncronas.
    • Para timeouts intermitentes, adicione novas tentativas para que uma falha transitória seja repetida: use as configurações de retry integradas da conexão HTTP v2 para chamadas de saída, ou um loop de retry RunOperation com script com um atraso entre as tentativas.
    • Se os timeouts se correlacionarem com a carga do agente, revise a capacidade do agente: execute operações que servem APIs em agentes separados de cargas de trabalho ETL pesadas e adicione agentes ao grupo se ele estiver saturado. Consulte Otimizar e melhorar o desempenho de agentes privados do Jitterbit.

Gateway privado retorna uma página 400 "verify Jitterbit Services" sem entrada no log de 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 de 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 de API para a solicitação com falha, porque a solicitação nunca chegou a uma operação.

  • Possível causa: O grupo de agentes privados está sobrecarregado e não possui threads de trabalho do Apache disponíveis para aceitar tarefas do gateway de API privado. Quando nenhuma thread de trabalho está livre, a transferência do gateway para o agente falha com uma redefinição 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 que os hosts dos agentes possuem CPU e memória suficientes.
    2. Monitore o uso de threads de trabalho do Apache dos agentes. Se a observabilidade nativa estiver ativada, revise os gráficos Apache Thread Capability, Apache idle workers e Apache busy workers (consulte Dashboards) para confirmar se as threads estão sendo esgotadas durante as falhas.
    3. Se os agentes ficarem consistentemente sem threads de trabalho do Apache mesmo após o dimensionamento, entre em contato com o suporte do Jitterbit para revisar a capacidade de threads de trabalho do Apache dos agentes (a configuração MaxRequestWorkers). Não altere os arquivos de configuração do Apache do Jitterbit a menos que orientado pelo suporte do Jitterbit. Consulte Arquivos de configuração do Apache.

Exibição e sincronização

API Portal não refletindo mudanças do projeto

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

Alterações de perfil de segurança levam vários minutos para entrarem em vigor

  • Sintoma: Uma API continua se comportando como se uma configuração de perfil de segurança antiga estivesse ativa, mesmo depois que o perfil foi atualizado e salvo.
  • Possível causa: Os perfis de segurança são armazenados em cache no gateway de API. As alterações em um perfil de segurança ativo não entram em vigor imediatamente.
  • Resolução:
    1. Aguarde vários minutos após salvar uma alteração de perfil de segurança antes de testar a API afetada.
    2. Se o problema persistir após 10 minutos, confirme que a alteração foi salva corretamente reabrindo o perfil de segurança.

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

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

Perfil de segurança não pode ser deletado enquanto ainda estiver atribuído a uma API publicada

  • Sintoma: A tentativa de deletar um perfil de segurança falha ou a opção de deletar fica indisponível, mesmo após remover o perfil de uma API.
  • Causa possível: Após remover um perfil de segurança da configuração de uma API, é necessário salvar e republicar a API antes que o perfil seja considerado totalmente removido. Até que a API seja republicada, o API Manager continua tratando o perfil como em uso.
  • Resolução:
    1. Após remover o perfil de segurança da API, clique em Salvar e depois Publicar a API.
    2. Após a API ser republicada com a configuração atualizada, o perfil de segurança deixará de aparecer como em uso e poderá ser deletado.

Problemas de gateway privado

OAuth de 2 etapas volta para 3 etapas em versões de gateway privado anteriores à 10.48

  • Sintoma: Um perfil de segurança configurado para OAuth de 2 etapas usa OAuth de 3 etapas 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 etapas. Se a versão do gateway for inferior à 10.48, o perfil de segurança volta para OAuth de 3 etapas mesmo quando OAuth de 2 etapas 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 ativar o suporte a OAuth de 2 etapas.

ALB multi-gateway: Todos os contêineres devem estar no mesmo host

  • Sintoma: Em um ambiente multi-gateway em contêiner atrás de um balanceador de carga de aplicativo (ALB), as chamadas de API falham intermitentemente ou as cargas úteis não podem ser recuperadas, mesmo que os gateways individuais pareçam saudáveis.
  • Causa possível: Ao usar um gateway de API privado em contêiner com um ALB, todos os contêineres de gateway devem ser executados no mesmo host. Contêineres implantados em hosts diferentes não conseguem coordenar a recuperação de carga útil, causando falhas intermitentes.
  • Resolução:
    1. Confirme que todos os contêineres de gateway de API privado no grupo estão sendo executados no mesmo host físico ou virtual.
    2. Se os contêineres estiverem distribuídos em 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 de configuração adicionais.

Gateway privado: Configuração SSL customizada é sobrescrita por atualizações

  • Sintoma: Após atualizar um gateway de API privado, as configurações de protocolo SSL customizado ou cifras deixam de ser aplicadas e o gateway volta ao comportamento TLS padrão.
  • Causa possível: O processo de atualização do gateway de API privado sobrescreve o arquivo de configuração local (/usr/local/openresty/nginx/conf/onpremise.conf). Qualquer alteração manual neste arquivo, incluindo restrições de protocolo SSL customizado ou listas de cifras, é perdida durante a atualização.
  • Resolução:
    1. Antes de atualizar o gateway de API privado, faça backup do arquivo de configuração local.
    2. Após a atualização ser concluída, reaplicar as configurações SSL customizado no novo arquivo de configuração.

Gateway privado retorna HTTP 507 ou "No such file or directory"

  • Sintoma: Endpoints do gateway de 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 abundante nos hosts do gateway.

  • Possível causa: Aqui, 507 significa que o gateway não conseguiu abrir o arquivo de payload ou resposta hospedado para a solicitação; não necessariamente indica que o host está sem armazenamento. Em um gateway de API privado com vários nós atrás de um balanceador de carga, isso pode acontecer quando o nó que atende 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 genuinamente sem armazenamento verificando o uso de disco e inode (df -h e df -i). Libere espaço e refaça o teste apenas se estiverem realmente cheios.
    2. Se o gateway é executado como vários nós atrás de um balanceador de carga, confirme que o balanceador 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 em contêineres, consulte Multi-gateway ALB: All containers must be on the same host.
    3. Se o erro persistir, ative o log 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 no servidor que não são configuráveis pelo cliente, como o mapeamento de host para ambiente, entradas de domínio privado obsoletas e permissões de arquivo.

Instalação ou atualização do gateway privado falha com dependências ausentes

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

    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

  • Possível causa: O gateway de API privado versão 10.62 e posterior requerem os pacotes geoip-devel e libGeoIP, fornecidos pelo repositório EPEL. A instalação documentada ativa 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 alcançar o EPEL para baixar os pacotes.

  • Resolução:

    • Em um host do gateway com acesso à internet, ative o repositório EPEL antes de instalar o gateway, conforme descrito em Install a private API gateway: execute yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm e depois 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 em ordem de dependência com yum install <package.rpm> antes de executar novamente a instalação do gateway.

Autoteste do gateway privado retorna "Failure, test call to API failed"

  • Sintoma: O utilitário de autoteste do gateway de API privado retorna:

    Failure, test call to API failed

  • Possível causa: Nas versões 11.30 e anteriores do gateway de API privado, o utilitário de autoteste cria uma API de teste com campos obrigatórios ausentes (Service Name e Path), causando a falha na chamada de teste.

  • Resolução:
    • Atualize o gateway de API privado para a versão 11.31 ou posterior, que resolve isso automaticamente.
    • Se não for possível atualizar imediatamente: abra a configuração da API para a API denominada ApiGatewayTest, preencha o campo Service Name com qualquer valor (por exemplo, service), defina Path como /, salve e publique, depois execute novamente o utilitário de autoteste.

Analytics e comportamento da API

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

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

API proxy: Hífens do cabeçalho da solicitação substituídos por underscores

  • Sintoma: Uma operação de API proxy recebe cabeçalhos de solicitação com hífens substituídos por underscores (por exemplo, X-Custom-Header chega como X_Custom_Header), causando falha nas buscas de cabeçalho.
  • Possível causa: 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 underscores. Para novas APIs proxy, essa configuração é definida como true (substituição desabilitada) por padrão. APIs proxy mais antigas podem ter a configuração definida como false, causando a substituição.
  • Resolução:
    • Na configuração da API proxy, verifique a configuração de cabeçalho disable-hyphen-replacement. Para preservar hífens nos nomes dos cabeçalhos, verifique se a configuração está como true.
    • Se a API proxy foi criada antes dessa configuração padrão ser introduzida e a substituição está ocorrendo de forma inesperada, atualize a configuração para true e republique a API.

Os logs de operação não aparecem 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 acionada pela API. Chamadas para WriteToOperationLog de dentro da operação também não produzem entradas de log visíveis.
  • Possível causa: Quando uma operação é acionada por uma API publicada, as execuções bem-sucedidas não aparecem nos logs de operação por padrão. Operações sem sucesso são sempre registradas; apenas os logs de operação bem-sucedidos e qualquer saída de WriteToOperationLog de execuções bem-sucedidas ficam ocultos. Execuções bem-sucedidas aparecem apenas quando Enable debug mode until (uma configuração do API Manager) ou Operation debug logging (uma configuração do agente) está ativa.
  • Resolução:
    1. Para ver logs de operação bem-sucedidos e saída de WriteToOperationLog, ative Enable debug mode until para a API na guia de configurações da API ou ative Operation debug logging no agente.
    2. Para também capturar os dados brutos de solicitação e resposta e cargas úteis, ative Enable debug mode until (conforme na etapa 1) ou combine Operation debug logging com Show Request & Response Payloads in Logs e Verbose logging. Quais dados cada configuração captura depende da combinação ativada; para o detalhamento completo, 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.

Carga útil de API disponível no agent por 2 dias

  • Sintoma: Um workflow que recupera uma carga útil de solicitação de API do agent mais de 2 dias após a API ter sido chamada não consegue encontrar a carga útil.
  • Possível causa: As cargas úteis de solicitação de API para APIs personalizadas e serviços OData são armazenadas no agent por um máximo de 2 dias. Após esse período, a carga útil fica disponível apenas se a operação já a tiver escrito em um conector de armazenamento persistente (como Temporary Storage, File Share ou um banco de dados).
  • Resolução:
    • Projete operações que consomem cargas úteis de solicitação de API para processar os dados imediatamente quando a API é chamada, em vez de adiar a recuperação da carga útil.
    • Se a carga útil precisar ser retida por um processamento mais longo, escreva-a em um local de armazenamento persistente na operação inicial acionada pela API.

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

  • Sintoma: A página API Logs não está exibindo as entradas de log esperadas, embora a API esteja funcionando com sucesso.
  • Possível causa: A página API Logs memoriza as seleções de filtro da sessão anterior. Um filtro aplicado anteriormente pode estar ocultando os resultados esperados.
  • Resolução: Na página API Logs, 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 Analytics APIs

  • Sintoma: Uma API não aparece no dropdown APIs na página Analytics, portanto os dados de análise dessa API não podem ser filtrados.
  • Possível causa: Apenas as APIs publicadas atualmente aparecem no dropdown APIs. As APIs que foram despublicadas são excluídas do dropdown, mesmo que existam logs de API para essas APIs.
  • Resolução:
    • Confirme que a API foi publicada. Para visualizar dados de análise, a API deve estar em estado publicado.
    • Para visualizar entradas de log de uma API não publicada, use a página API Logs em seu lugar. 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 da organização subitamente retornam erros HTTP 429.
  • Possível causa: A organização esgotou seu limite mensal de chamadas de API conforme definido por 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 APIs. O limite é redefinido no primeiro dia do mês seguinte.
    • Para evitar atingir o limite, configure limites de taxa no nível de ambiente ou perfil de segurança usando a configuração Hits per minute para distribuir a carga e aplicar limites de consumo por consumidor.
    • Para aumentar o limite mensal de chamadas da sua organização, entre em contato com seu Customer Success Manager.

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

  • Sintoma: Um consumidor ou aplicação específica recebe erros HTTP 429 ao chamar uma API, enquanto outros consumidores conseguem chamar a mesma API com sucesso.
  • Possível causa: O perfil de segurança atribuído à API tem grupos de IP confiável 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 sua configuração de grupo de IP confiável.
    2. Adicione o endereço IP do consumidor ou intervalo de endereços a um grupo de IP confiável existente, ou crie um novo grupo de IP confiável que inclua os endereços necessários.

Limite de taxa no nível da plataforma: 200 requisições por minuto

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

Rede e conectividade

Zscaler ou firewall com interceptação SSL bloqueia 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 por Zscaler ou similar com inspeção SSL.
  • Possíveis causas:
    • Zscaler e proxies de segurança similares executam inspeção SSL/TLS interceptando tráfego HTTPS e assinando novamente com seu próprio certificado CA. Sistemas cliente que não confiam na CA raiz do Zscaler rejeitam a conexão.
    • Importar manualmente o certificado Jitterbit no armazenamento de confiança não é uma solução confiável: quando Jitterbit renova seu certificado, a cópia importada manualmente fica desatualizada e quebra a conexão novamente.
  • Resolução:
    • Instale o certificado CA raiz do Zscaler no armazenamento de confiança do SO ou navegador nos sistemas que fazem as chamadas de API, para que 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 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-configuration) da organização para confirmar que os endpoints Jitterbit são tratados corretamente.
    • Não importe manualmente o certificado folha Jitterbit em um armazenamento de confiança como solução: use a CA raiz do Zscaler em vez disso para evitar problemas quando Jitterbit renovar seu certificado.