Ir para o conteúdo

Solução de problemas de 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 seu 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

Estas etapas se aplicam à maioria dos problemas do API Manager e são 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, que podem ajudar a estreitar a causa.

Para capturar também os payloads completos de requisição e resposta, use o modo de depuração, a melhor opção para solução de problemas ativa: ele captura dados de requisição e resposta junto com logs detalhados no 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 personalizadas, serviços OData ou APIs proxy.
  2. Reproduza a requisição e revise os payloads nos logs da API.

Nota

Para registrar payloads de forma contínua em vez de em uma janela de solução de problemas fixa, use Log 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 de status do sistema Jitterbit e a página de 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 o URI de redirecionamento OAuth seja construído 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 espaços (por exemplo, altere My Profile para MyProfile ou my-profile).
    2. No registro do aplicativo Azure, verifique se as URLs de resposta registradas lá correspondem ao 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 pelo Entra ID não corresponde ao público 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á mal configurada, 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 o público e o escopo estarem corretos, 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 descontinuada

  • 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. 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 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 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 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. Consulte Conectar um agente de IA do Jitterbit ao Microsoft Copilot Studio.

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

  • Sintoma: O botão New 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 a permissão Admin ao usuário no nível da organização faz o botão aparecer, mas também expõe todos os ambientes ao usuário.
  • Possível causa: Uma função no nível da organização sozinha não é suficiente para criar APIs. A função também deve ter acesso de Write concedido no nível do ambiente para o ambiente específico onde o usuário precisa criar APIs.
  • Resolução:
    1. No Management Console, acesse Environments 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 Write está habilitado. Se não estiver, habilite-o e salve.
    3. O botão New API agora deve estar visível para esse ambiente.
  • Sintoma: Uma API com dois ou mais perfis de segurança de autenticação Basic security profiles 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 solicitações falham com um erro 401 Unauthorized.
  • Possível causa: O navegador ou cliente da 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 em cache primeiro. Se as credenciais em cache não corresponderem a nenhum dos perfis de segurança configurados, a solicitação é rejeitada e o nome de usuário inesperado aparece nos logs antes da autenticação 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 testar novamente a API.
    2. Confirme que o comportamento não está presente quando uma solicitação nova é feita sem cookies de sessão anterior. Se o erro desaparecer, o problema é o armazenamento em cache de credenciais no lado do cliente e não 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 apresentar o mesmo comportamento.

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

  • Sintoma: As chamadas da 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á substituindo os grupos de IP confiáveis ativos.
  • Resolução: Migre o perfil de segurança de intervalos de IP legados para o modelo Trusted IP Groups, 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 Trust requests only from the following IP ranges em um perfil que ainda usa intervalos de IP legados remove permanentemente esses intervalos (um prompt de confirmação avisa sobre isso), portanto, migre os IPs para um grupo de IP confiável em vez de desativar a configuração para limpar o cache.

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 em rascunho não contam.

  • Resolução: Na página APIs do API Manager, verifique as contagens de Custom API URLs used e Proxy API URLs used, mostradas na parte superior da página, em relação aos totais permitidos pela sua assinatura. Cancele a publicação 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 Customer Success Manager.

API publicada retorna 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 está 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, URL base ou configurações de visibilidade da API 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 se 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 APIs, verifique se a API foi publicada com sucesso e se sua URL e configurações de visibilidade estão corretas.
    • Se a API é servida através de 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 múltiplos endpoints.
    • Para APIs proxy, confirme que a combinação da URL base e todos os caminhos de serviço definidos permaneça dentro do limite de 8.000 caracteres.

API proxy: Parâmetros de caminho de serviço exigem 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 chaves.
  • Possível causa: 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 defina os caminhos e seus parâmetros. O API Manager 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 API Manager

  • Sintoma: Excluir 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 de Admin. Excluir uma API primeiro verifica quais Grupos de API a API está associada e visualizar a página Grupos de API requer a permissão de Admin: uma função com apenas acesso de ambiente Write pode abrir a página, mas não consegue 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: Peça a um usuário cuja função tenha a permissão de função de Admin que execute a exclusão. Conceder à função afetada a permissão de Admin também funciona, mas essa é uma elevação ampla no nível da organização, portanto 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 proxy para um ambiente diferente, clone a API na página de APIs e selecione o ambiente correto durante a clonagem.
    • Como alternativa, exporte a API do seu ambiente atual e importe-a no ambiente de destino.

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

  • Sintoma: Após ativar CORS em uma API personalizada ou proxy, o método HTTP OPTIONS processa requisições sem autenticação.
  • Possível causa: Ativar CORS faz com que operações que usam 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. Este é o comportamento esperado quando CORS está ativado.
    • Se for necessário o tratamento autenticado de OPTIONS, desative 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 ser acessível publicamente

  • Sintoma: Uma API proxy que usa o gateway de API em nuvem hospedado pela Jitterbit retorna erros ou não consegue alcançar a API de destino.
  • Possível causa: Ao usar o gateway de API em nuvem, a API sendo proxificada deve ser 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 é acessível pela 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 adicionar os endereços IP do gateway em nuvem à lista de permissões para que o gateway possa acessar a API proxificada, consulte Informações de lista de permissões.

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

  • Sintoma: O botão Mostrar Payloads de Requisição e Resposta nos Logs aparece nas configurações de uma API proxy, mas ativá-lo não tem efeito na saída de logs.
  • Possível causa: O registro de payload de requisiçã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 requisição e resposta, use uma API personalizada que chame o mesmo endpoint, onde a configuração Mostrar Payloads de Requisição e Resposta nos Logs é suportada.

Desempenho e tempos limite

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, causando falha no gateway ao rotear a solicitação.
    • A operação de backend ou serviço externo é muito lento para responder dentro da janela de timeout do gateway, por exemplo, devido a grandes payloads 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, então expira no gateway antes da operação ser executada. Um sinal desse caso é que a solicitação com falha não tem entrada correspondente nos logs de operação.

  • Resolução:

    • Verifique se a URL da API está corretamente formada. Se a API usa parâmetros de caminho, considere adicionar um script à operação que analise explicitamente a URL e capture os valores dos parâmetros.
    • Se o timeout for causado por um backend lento, revise a operação e sua lógica de transformação para identificar gargalos de desempenho, particularmente grandes payloads de dados ou chamadas externas lentas, e reduza a etapa lenta.
    • Se a operação realmente requer mais tempo do que a configuração atual permite, aumente o timeout na aba de configurações da API. O timeout da API (padrão 30 segundos, máximo 180 segundos) é independente do timeout de operação do Studio; o timeout de 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 dentro do timeout máximo, ou 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 aguardar sua conclusão. Consulte Gerenciar operações assíncronas.
    • Para timeouts intermitentes, adicione 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 atraso entre as tentativas.
    • Se os timeouts 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 dos agentes privados Jitterbit.

Gateway privado retorna uma página 400 "verify Jitterbit Services" 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 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 tem threads de trabalho Apache disponíveis para aceitar trabalhos do gateway de API privado. Quando nenhuma thread de trabalho está livre, a transferência de gateway para 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 têm CPU e memória suficientes.
    2. Monitore o uso de threads de trabalho Apache dos agentes. Se a observabilidade nativa estiver habilitada, 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 consistentemente ficarem sem threads de trabalho Apache mesmo após dimensionamento, 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 Apache do Jitterbit a menos que seja direcionado pelo suporte Jitterbit. Consulte Arquivos de configuração Apache.

Exibição e sincronização

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

  • Sintoma: O API Portal exibe nomes ou atributos de projeto desatualizados após um projeto ser renomeado ou atualizado.
  • Possível causa: O API Portal não sincronizou 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 aparecem corretamente no API Portal.

As alterações do perfil de segurança levam vários minutos para entrar em vigor

  • Sintoma: Uma API continua se comportando como se uma configuração de perfil de segurança antiga estivesse ativa, mesmo após o perfil ter sido 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 se 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 da API antes de excluí-la para remover a entrada do Portal primeiro.

Não é possível excluir o perfil de segurança enquanto ainda está atribuído a uma API publicada

  • Sintoma: A tentativa de 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.
  • Possível causa: 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 API Manager ainda trata o perfil como em uso.
  • Resolução:
    1. Após desatribuir o perfil de segurança da API, clique em Save e depois em Publish na API.
    2. Após a API ser republicada com a configuração atualizada, o perfil de segurança não será mais exibido como em uso e poderá ser excluído.

Problemas do gateway privado

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

  • Sintoma: Um perfil de segurança configurado para OAuth de 2 etapas usa OAuth de 3 etapas quando servido por um gateway de API privado.
  • Possível causa: Os gateways de API privados anteriores à versão 10.48 não suportam OAuth de 2 etapas. Se a versão do gateway for anterior à 10.48, o perfil de segurança retorna 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 containerizado atrás de um balanceador de carga de aplicação (ALB), as chamadas de API falham intermitentemente ou os payloads não podem ser recuperados, mesmo que os gateways individuais pareçam saudáveis.
  • Possível causa: Ao usar um gateway de API privado containerizado com um ALB, todos os contêineres do gateway devem ser executados no mesmo host. Contêineres implantados em hosts diferentes não conseguem coordenar a recuperação de payload, causando falhas intermitentes.
  • Resolução:
    1. Confirme que todos os contêineres do 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: A configuração SSL personalizada é sobrescrita por atualizações

  • Sintoma: Após atualizar um gateway de API privado, as configurações personalizadas de protocolo SSL ou cipher não são mais aplicadas e o gateway reverte para o comportamento TLS padrão.
  • 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). Qualquer alteração manual neste arquivo, incluindo restrições de protocolo SSL personalizadas ou listas de cipher, é 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 conclusão da atualização, reaplique suas configurações SSL personalizadas ao novo arquivo de configuração.

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

  • Sintoma: Os 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 significa necessariamente que o host está sem armazenamento. Em um gateway de API privado com múltiplos 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 para 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 teste novamente apenas se estiverem realmente cheios.
    2. Se o gateway é executado 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 para o nó que os criou. Para gateways containerizados, consulte ALB multi-gateway: Todos os contêineres devem estar no mesmo 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 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 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.

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ê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

  • Possível causa: O gateway de API privado versão 10.62 e posterior exigem os pacotes geoip-devel e libGeoIP, fornecidos pelo repositório EPEL. A instalação documentada habilita o EPEL antes de instalar o gateway. O erro ocorre quando essa etapa é ignorada 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 e 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 de linha de comando 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 que não possui campos obrigatórios (Nome do Serviço e Caminho), causando falha na chamada de teste.

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

Análise e comportamento de 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 do 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 de proxy: hífens do cabeçalho de solicitação substituídos por sublinhados

  • Sintoma: Uma operação de API de 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 falha nas buscas de cabeçalho.
  • Possível causa: APIs de proxy têm uma configuração disable-hyphen-replacement que controla se hífens em nomes de cabeçalhos de solicitação são substituídos por sublinhados. Para novas APIs de proxy, essa configuração é padronizada como true (substituição desabilitada). APIs de proxy mais antigas podem ter a configuração como false, causando a substituição.
  • Resolução:
    • Na configuração de API de proxy, verifique a configuração de cabeçalho disable-hyphen-replacement. Para preservar hífens em nomes de cabeçalhos, certifique-se de que a configuração é true.
    • Se a API de proxy foi criada antes dessa configuração padrão ser introduzida e a substituição está ocorrendo inesperadamente, atualize a configuração para true e republique a API.

Os logs de operação não ficam 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 acionada pela API. As 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 meio de uma API publicada, as execuções bem-sucedidas não aparecem nos logs de operação por padrão. As operações malsucedidas sempre são registradas; apenas os logs de operação bem-sucedidos e qualquer saída de WriteToOperationLog de execuções bem-sucedidas ficam ocultos. As execuções bem-sucedidas aparecem apenas quando Ativar modo de depuração até (uma configuração do API Manager) ou Log de depuração de operação (uma configuração do agente) está ativo.
  • Resolução:
    1. Para ver os logs de operação bem-sucedidos e a saída de WriteToOperationLog, ative Ativar modo de depuração até para a API na guia de configurações da API, ou ative Log de depuração de operação no agente.
    2. Para também capturar os dados brutos de solicitação e resposta e os payloads, ative Ativar modo de depuração até (como na etapa 1) ou combine Log de depuração de operação com Mostrar payloads de solicitação e resposta nos logs e Log detalhado. 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.

Payload da API 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: Os payloads de solicitação de API para APIs personalizadas e serviços OData são armazenados no agente por um máximo de 2 dias. Após esse período, o payload fica disponível apenas se a operação já o tiver gravado em um conector de armazenamento persistente (como Armazenamento Temporário, Compartilhamento de Arquivo 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 para 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 as seleções de filtro anteriores

  • Sintoma: A página Logs da API não mostra 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 menu suspenso de APIs do Analytics

  • Sintoma: Uma API não aparece no menu suspenso APIs na página Analytics, portanto, os dados de análise dessa API não podem ser filtrados.
  • Possível causa: Apenas as APIs atualmente publicadas aparecem no menu suspenso APIs. As APIs que foram despublicadas são excluídas do menu suspenso, mesmo que existam logs de API para essas APIs.
  • Resolução:
    • Confirme se 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 Logs da API em vez disso. Os dados de log permanecem disponíveis lá, mas não podem ser filtrados por nome de API.

Limitação de taxa

Erro 429: Limite mensal de chamadas de API excedido

  • Sintoma: Todas as APIs da organização retornam repentinamente erros HTTP 429.
  • Possível causa: 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 APIs. O limite é reiniciado 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 aplicar limites de consumo por consumidor.
    • Para aumentar o limite mensal de chamadas da sua organização, entre em contato com seu Gerente de Sucesso do Cliente.

Erro 429: IP do consumidor fora do intervalo 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 dos intervalos permitidos 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 ou intervalo de endereços do consumidor 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 solicitações por minuto

  • Sintoma: APIs hospedadas no gateway de API em 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 em nuvem gerenciado pela Jitterbit aplica um limite no nível da plataforma de 200 solicitações de API por minuto por organização, compartilhado entre todos os tipos de API (personalizada, 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 as 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 uma taxa de transferência sustentada acima deste limite, implante um gateway de API privado onde a taxa de transferência é determinada 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 realizam inspeção SSL/TLS interceptando tráfego HTTPS e assinando-o novamente com seu próprio certificado de 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 de 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 alternativa: use a CA raiz do Zscaler em vez disso para evitar problemas quando Jitterbit renova seu certificado.