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.

Verifique os logs da API

Revise os logs da API para erros de requisiçã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 estreitar a causa.

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

  1. Na aba Settings da configuração da API, ative Enable debug mode until e defina uma data para mantê-lo ativo. Consulte a referência de configuração para APIs customizadas, serviços OData ou APIs proxy.
  2. Reproduza a requisição e revise os payloads nos logs da API.

Nota

Para registrar payloads continuamente em vez de uma janela de troubleshooting fixa, use Verbose logging ou Show Request & Response Payloads in Logs para serviços customizados e OData.

Verifique o status do sistema Jitterbit

Se um problema parecer afetar todas as APIs ou a interface do API Manager em si, 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 de 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 causam a construção incorreta do URI de redirecionamento OAuth, 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, mude My Profile para MyProfile ou my-profile).
    2. No registro de aplicativo do Azure, verifique se as URLs de resposta registradas correspondem ao 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 perfil de segurança OAuth 2.0 de 2 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 à audiência configurada no perfil de segurança do API Manager. Isso geralmente indica que o URI da ID do Aplicativo no registro de aplicativo do Azure está configurado incorretamente, ou o escopo OAuth que o cliente está solicitando não corresponde ao URI registrado.

  • Resolução:
    1. No portal do Azure, abra o registro de aplicativo atribuído a este perfil de segurança e acesse Expor uma API.
    2. Confirme se o URI da ID do Aplicativo está definido como um URI válido 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 depois que a audiência e o escopo estiverem corretos, abra o manifesto do registro de 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 desativada

  • Sintoma: As 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 de aplicativo do perfil de segurança ainda está configurado para usar a API do Azure AD Graph, que a Microsoft desativou 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 de 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 é compatível

  • 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 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 no 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 "Nova API" não visível apesar da função de organização correta

  • Sintoma: O botão Nova API não aparece no Gerenciador de API 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 Escrita concedido no nível do ambiente para o ambiente específico onde precisa 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 Escrita está ativado. Se não estiver, ative-o e salve.
    3. O botão Nova API agora deve ficar visível para esse ambiente.
  • Sintoma: Uma credencial de autenticação básica 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 da 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 de 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 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 perfil de segurança atribuído, a solicitação é rejeitada e o nome de usuário inesperado aparece nos logs antes da autenticação bem-sucedida com as credenciais corretas. Se corresponderem, a solicitação é bem-sucedida sem um novo aviso.

  • Resolução:

    1. Limpe os cookies e o cache do navegador, ou mude para uma janela de navegação incógnita ou privada, antes de testar novamente a API.
    2. Confirme que o comportamento não está presente quando uma solicitação recente é feita sem cookies de sessão anterior. Se o comportamento desaparecer, trata-se de 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 Personalizada Registro falha com um erro INVALID_TRIGGER_USER ou TRIGGER_USER_TOO_LONG, mesmo que as mesmas credenciais ou valor de cabeçalho funcionassem 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 ultrapassa 256 caracteres (TRIGGER_USER_TOO_LONG).

A validação de caracteres foi adicionada no lançamento Harmony 12.10, e o limite de comprimento foi adicionado no lançamento Harmony 12.11. Um gateway de API privada 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 do lançamento Harmony 12.12, o campo Nome de usuário do perfil de segurança rejeita os caracteres não permitidos, portanto, não é possível mais salvar um perfil de segurança que os contenha. Para autenticação Basic com a configuração padrão de Logging, INVALID_TRIGGER_USER aplica-se apenas aos perfis de segurança salvos antes desse lançamento.

  • 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 a 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 cabeçalho que não contenha os caracteres não permitidos e possua 256 caracteres ou menos.

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

  • Sintoma: As 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 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 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 alteração dos 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 organização do Salesforce migrar para Hyperforce, a infraestrutura de nuvem pública do Salesforce. O perfil de segurança da API tem Trust requests only from the following IP ranges habilitado com um grupo de IP confiável que lista endereços IP do Salesforce.

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

  • Resolução: O Salesforce recomenda autenticar as chamadas em sua rede em vez de adicionar à lista de permissões 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 cabeçalho de solicitação, não em um parâmetro de consulta, para que não seja registrada nas URLs de solicitação. OAuth 2.0 também está disponível, embora com o Salesforce como provedor de identidade o único fluxo seja 3-legged, que requer interação manual.
  • Após a autenticação bem-sucedida do callout, desatribua o grupo de IP confiável que lista os endereços do Salesforce, para que mudanças 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, o que remove permanentemente qualquer intervalo de IP legado ainda mantido no perfil.

    Se sua organização exigir lista de permissão de IP, o Salesforce publica seus intervalos do Hyperforce como uma lista dinâmica em ip-ranges.salesforce.com/ip-ranges.json, anunciando adições com antecedência. Essa lista muda toda vez que o Salesforce altera seus endereços, portanto manter uma lista de permissão atualizada significa rastrear o arquivo e atualizar o grupo de IP confiável para corresponder a ele. Callouts de um endereço adicionado desde a última atualização do grupo são rejeitados. Esses endereços também são compartilhados entre organizações do Salesforce, portanto colocá-los na lista de permissão confirma de onde uma solicitação veio, não que veio da sua organização. Para obter orientações completas do Salesforce, incluindo SSL bidirecional (mTLS), Provedores de Autenticação e aplicativos conectados, consulte Manter acesso ininterrupto aos serviços 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 de 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 de URLs de API personalizada usadas e URLs de API de proxy usadas, mostradas na parte superior 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 para o limite). Para aumentar o limite, entre em contato com seu Gerenciador 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 Ocorrências por minuto no perfil de segurança atribuído está definido como zero, bloqueando todas as solicitações. Uma mudança no nível de assinatura da organização pode redefinir esse limite, então 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 que o valor de Ocorrências por minuto está definido como um número diferente de zero. Se o limite foi redefinido recentemente (por exemplo, após uma mudança 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 é servida por um gateway de API privada, verifique a instalação do gateway e a conectividade para qualquer erro ou configuração incorreta.

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

  • Sintoma: O gateway de API retorna:

    414 URI Too Large
    
  • Possível causa: A URL de serviço construída (incluindo URL base, caminho de serviço e quaisquer parâmetros de caminho ou consulta) excede 8.000 caracteres.

  • Resolução:
    • Reduza o comprimento da URL de serviço encurtando o caminho de 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.

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 de Admin. A exclusão de uma API primeiro verifica quais Grupos de API a API está associada, e visualizar a página de 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: Faça com que um usuário cuja função tenha a permissão de Admin role permission realize a exclusão. Conceder à função afetada a permissão de Admin também funciona, mas essa é uma elevação ampla no nível organizacional, então prefira ter um administrador existente excluir a API.

O ambiente de 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.
    • Alternativamente, exporte a API de seu ambiente atual e importe-a para o ambiente de destino.

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

  • Sintoma: Após habilitar CORS em uma API personalizada ou proxy, o método HTTP OPTIONS processa solicitaçõ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 solicitações de preflight do navegador, mas significa que qualquer solicitação OPTIONS atinge a 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 o tratamento autenticado de OPTIONS for necessário, desabilite CORS na API ou reestruture a operação para detectar e tratar explicitamente solicitações de preflight não autenticadas.

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

  • Sintoma: Uma API proxy usando o gateway de API em nuvem hospedado pela Jitterbit retorna erros ou não consegue alcançar a API de destino.
  • Causa possível: Ao usar o gateway de API em nuvem, a API sendo proxiada 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 seja 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 autorizar os endereços IP do gateway em nuvem de modo que o gateway possa acessar a API proxiada, consulte Informações de autorização.

A configuração Mostrar payloads de solicitação e resposta não tem efeito para APIs proxy

  • Sintoma: O botão de alternância Mostrar payloads de solicitação e resposta nos logs aparece nas configurações de uma API proxy, mas habilitá-lo não tem efeito na saída de log.
  • Causa possível: O registro de payload de solicitação e resposta não é suportado para APIs proxy. O botão de alternância é 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 chame o mesmo endpoint, onde a configuração Mostrar payloads de solicitação e resposta nos logs é suportada.

Desempenho e tempos limite

HTTP 504 Gateway Timeout

  • Sintoma: As chamadas de API retornam:

    504 Gateway Timeout
    

    Isso geralmente ocorre após a janela de tempo limite do gateway (30 a 180 segundos, dependendo da configuração de tempo limite 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 é muito lento para responder dentro da janela de tempo limite do gateway, por exemplo, por causa de 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á em concorrência máxima ou sob carga pesada, então o tempo limite expira no gateway antes da operação ser executada. Um sinal desse caso é que a solicitação com falha não tem nenhuma entrada correspondente nos logs de operação.
  • Resolução:

    • Verifique se a URL da API está formada corretamente. 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, analise a operação e sua lógica de transformação em busca de gargalos de desempenho, particularmente grandes payloads de dados ou chamadas externas lentas, e reduza a etapa lenta.
    • Se a operação realmente precisar de 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 30 segundos, máximo 180 segundos) é independente do tempo limite de operação do Studio; o tempo limite 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 tempo limite 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 esperar que seja concluída. Consulte Gerenciar operações assíncronas.
    • Para tempos limite intermitentes, adicione tentativas para que uma falha transitória seja repetida: use as configurações de tentativa integradas da conexão HTTP v2 para chamadas de saída ou um loop de tentativa RunOperation com script com um atraso entre as tentativas.
    • Se os tempos limite se correlacionarem com a carga do agente, analise a capacidade do agente: execute operações de atendimento de API em agentes separados de cargas de trabalho ETL pesadas e adicione agentes ao grupo se estiver saturado. Consulte Otimizar e melhorar o desempenho de agentes privados Jitterbit.

Gateway privado retorna uma página 400 "verify Jitterbit Services" sem entrada de log da API

  • Sintoma: Requisiçõ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 similar a:

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

    Nenhuma entrada aparece nos logs da API para a requisição que falhou, porque a requisiçã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 jobs do gateway de API privado. Quando nenhuma thread de trabalho está livre, o handoff do gateway para o agente falha com uma redefinição de conexão antes da requisição poder ser registrada ou executada.

  • Resolução:
    1. Adicione mais agentes ao grupo de agentes para distribuir a carga e confirme que as máquinas 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 ativada, revise os gráficos Apache Thread Capability, Apache idle workers e Apache busy workers (consulte Painéis) 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 escalar, entre em contato com o suporte Jitterbit para revisar a capacidade de threads de trabalho Apache dos agentes (configuração MaxRequestWorkers). Não altere os arquivos de configuração Apache do Jitterbit a menos que orientado pelo suporte Jitterbit. Consulte Arquivos de configuração Apache.

Exibição e sincronização

API Portal não refletindo alterações de 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 sincronizou automaticamente após a alteração do projeto.
  • Resolução:
    1. Para atualizar todas as APIs customizadas e de proxy no ambiente, abra o Portal Manager e clique em Regenerate Docs. Para atualizar uma única API, abra a aba 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 surtir efeito

  • 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: Perfis de segurança são armazenados em cache no gateway de API. Alterações em um perfil de segurança ativo não surtam efeito 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 é automaticamente atualizada 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 aba Documentation para a API antes de excluí-la para remover a entrada do Portal primeiro.

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

  • Sintoma: A tentativa de excluir um perfil de segurança falha ou a opção de exclusão fica indisponí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 API Manager ainda trata o perfil como em uso.
  • Resolução:
    1. Depois de desatribuir o perfil de segurança da API, clique em Salvar e depois Publicar a API.
    2. Depois que a API for republicada com a configuração atualizada, o perfil de segurança não aparecerá mais como em uso e poderá ser excluído.

Problemas do gateway privado

OAuth de 2 etapas retorna 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 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.

Multi-gateway ALB: todos os contêineres devem estar no mesmo host

  • Sintoma: Em um ambiente multi-gateway em contêineres atrás de um balanceador de carga de aplicativo (ALB), as chamadas de API falham intermitentemente ou os payloads não podem ser recuperados, mesmo que os gateways individuais pareçam íntegros.
  • Causa possível: Ao usar um gateway de API privado em contêiner com um ALB, todos os contêineres do gateway devem executar 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 de gateway de API privado no grupo estão sendo executados no mesmo host físico ou virtual.
    2. Se os contêineres estiverem espalhados por vários hosts, consolide-os em um único host.
    3. Para implantações em multi-host, consulte a configuração de ALB no guia de instalação do gateway para requisitos de configuração adicionais.

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

  • Sintoma: Após atualizar um gateway de API privado, as configurações de protocolo SSL personalizado ou de cifra não são mais aplicadas e o gateway reverte para o 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). Alterações manuais neste arquivo, incluindo restrições de protocolo SSL personalizado ou listas de cifra, são perdidas 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: Pontos de extremidade 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 refaça o teste 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 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êiner, consulte Multi-gateway ALB: 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 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 dos 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 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ê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: A versão 10.62 e posterior do gateway de API privado exigem 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 é 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 do gateway com acesso à internet, ative o repositório EPEL antes de instalar o gateway, conforme descrito em Instalar um gateway de API privada: execute yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm e, 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 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 da 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 (Service Name e Path), 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 a atualização imediata não for possível: abra a configuração da API para a API chamada ApiGatewayTest, preencha o campo Service Name com qualquer valor (por exemplo, service), defina Path como /, salve e publique, então 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 de sistema $count ou $inlinecount retorna um erro em vez de 0 quando nenhum registro corresponde ao filtro.
  • Causa possível: 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 no 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 pesquisas de cabeçalho.
  • Causa possível: As APIs de proxy têm uma configuração disable-hyphen-replacement que controla se os hífens nos 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 definido como false, causando a substituição.
  • Resolução:
    • Na configuração da API de proxy, verifique a configuração de cabeçalho disable-hyphen-replacement. Para preservar hífens nos 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.

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 da operação acionada pela API. Chamadas para WriteToOperationLog dentro da operação também não produzem entradas de log visíveis.
  • Causa possível: Quando uma operação é acionada por 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ção bem-sucedidos e qualquer saída de WriteToOperationLog de execuções bem-sucedidas são ocultos. 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á ativa.
  • Resolução:
    1. Para ver logs de operação bem-sucedidos e saída de WriteToOperationLog, ative Ativar modo de depuração até da API na guia de configurações de API, ou ative Log de depuração de operação no agente.
    2. Para também capturar dados e cargas úteis de solicitação e resposta brutos, ative Ativar modo de depuração até (como na etapa 1) ou combine Log de depuração de operação com Mostrar cargas úteis de solicitação e resposta em logs e Log detalhado. Quais dados cada configuração captura depende da combinação ativada; para ver o detalhamento completo, consulte Dados de solicitação e resposta de 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 agente por 2 dias

  • Sintoma: Um fluxo de trabalho que recupera uma carga útil de solicitação de API do agente mais de 2 dias após a chamada da API 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 agente 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 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 consumam cargas úteis de solicitação de API para processar os dados imediatamente quando a API for chamada, em vez de adiar a recuperação da carga útil.
    • Se a carga útil precisar ser retida para processamento mais longo, grave-a em um local de armazenamento persistente na operação inicial acionada pela API.

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

  • Sintoma: A página API Logs não mostra entradas de log esperadas mesmo que a API esteja sendo executada com sucesso.
  • Possível causa: A página API Logs 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 API Logs, revise todos os filtros ativos e limpe aqueles que possam estar excluindo as entradas esperadas.

APIs não publicadas não aparecem na lista suspensa de APIs do Analytics

  • Sintoma: Uma API não aparece na lista suspensa 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 na lista suspensa APIs. As APIs que foram canceladas não aparecem na lista suspensa, 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. 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 de chamadas atual 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 Customer Success Manager.

Erro 429: IP do consumidor não está no intervalo de IP confiável

  • 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.
  • Possível causa: O perfil de segurança atribuído à API tem grupos de IP confiáveis 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 a configuração do seu grupo de IP confiável.
    2. Adicione o endereço IP do consumidor ou o 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 em nuvem gerenciado pela Jitterbit sofrem limitação ou são 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.
  • Causa possível: O gateway de API em 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 a gateways de API privados.
  • Resolução:
    • Analise 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 requisições por minuto.
    • Se seu caso de uso exigir vazão sustentada acima deste limite, implante um gateway de API privado onde a vazão é 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 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 repositório 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 repositório de confiança do SO ou navegador nos sistemas que realizam chamadas de API, para que certificados assinados novamente 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.
    • Analise 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 repositório de confiança como solução alternativa: use a CA raiz do Zscaler para evitar problemas quando Jitterbit renova seu certificado.