Quando as solicitações de API são feitas pela Apigee, os componentes da Apigee roteadores e processadores de mensagens ou os servidores de
back-end podem retornar erros aos aplicativos cliente.
Erros do processador de mensagens
O Processador de mensagens é o principal componente da Apigee que processa as políticas e
interage com os servidores de back-end. Ele pode retornar erros se detectar algum problema como:
Problemas de conectividade de rede, falhas no handshake do TLS, indisponibilidade do servidor de back-end, falta de resposta durante a comunicação com o servidor de back-end
Falhas durante a execução da política
Cabeçalhos HTTP inválidos, codificação, caminho, não conformidade com as especificações HTTP, excedendo
os limites de produtos etc.:
Com solicitação HTTP enviada pelos aplicativos cliente
OU
Com resposta HTTP enviada pelo servidor de back-end
E muito mais
Exemplo de erro do processador de mensagens
O Processador de mensagens sempre retorna um código de status HTTP seguido por uma mensagem de erro junto com um código de erro no formato JSON, conforme mostrado abaixo:
O aplicativo cliente recebe um código de resposta como o exemplo a seguir:
HTTP/1.1 504 Gateway Timeout
Uma resposta de erro do Processador de mensagens aparece no seguinte formato:
Contém a mensagem de erro que descreve a possível causa do erro
errorcode
Código do erro (também conhecido como código de falha) associado ao
erro
reason
Contém uma mensagem que indica o possível motivo do erro
Catálogo de erros de tempo de execução
Este catálogo de erros fornece todas as informações que você precisa saber sobre os códigos de erro de ambiente de execução (para erros não relacionados à política) que são retornados pelo componente Processador de mensagens da Apigee. Ele inclui as seguintes informações sobre cada código de erro:
Código de status HTTP
Mensagem de erro
Motivo do erro (nem todas as mensagens de erro exibem
reason)
Possíveis causas do erro
Todas as especificações HTTP associadas e/ou limites de produto
Manuais e vídeos que contêm instruções para diagnosticar a causa do erro e
soluções eficazes que podem ser aplicadas para resolver o erro por conta própria (quando disponível)
Corrija isso para corrigir o erro
As seguintes categorias de código de erro são abordadas:
Use a caixa Pesquisar abaixo para filtrar a tabela e exibir as informações acima para um código de erro específico. É possível pesquisar o código de status ou qualquer conteúdo em qualquer campo
na tabela.
searchPesquisa
Código do erro
Descrição
Correção
flow.*
flow.APITimedOut
Código de status HTTP:
504 Gateway Timeout
Mensagem de erro:
API timed out
Possível causa:
Este erro ocorre se:
O servidor de back-end não responde dentro do período de tempo limite configurado pela propriedade api.timeout para o proxy de API específico.
Uma política leva muito tempo devido a operações intensivas em termos de computação, carga alta
ou desempenho ruim.
flow.SharedFlowNotFound
Código de status HTTP:
500 Internal Server Error
Mensagem de erro:
Shared Flow {shared_flow_name} Not Found
Possível causa:
Esse erro ocorre se o fluxo compartilhado específico:
A codificação especificada no cabeçalho da solicitação HTTP
Content-Encoding é válida e compatível com a Apigee,
MAS
O formato de payload enviado pelo cliente como parte da solicitação HTTP não corresponde ao formato de codificação especificado no cabeçalho Content-Encoding.
A codificação especificada no cabeçalho de resposta HTTP do servidor de back-end/destino Content-Encoding é válida e aceita pela Apigee,
MAS
O formato de payload enviado pelo servidor de back-end/destino como parte da resposta HTTP não corresponde ao formato de codificação especificado no cabeçalho Content-Encoding
messaging.adaptors.http.flow.ErrorResponseCode
Código de status HTTP:
500
Mensagem de erro:
A mensagem de erro e o formato podem variar dependendo da implementação do servidor de back-end.
Possível causa:
Esse erro ocorre se o servidor de back-end responder com o código de status 500 para a Apigee.
Código de status HTTP:
503
Mensagem de erro:
A mensagem de erro e o formato podem variar dependendo da implementação do servidor de back-end.
Possível causa:
Esse erro ocorre se o servidor de back-end responder com o código de status 503 para a Apigee.
Código de status HTTP:
504
Mensagem de erro:
A mensagem de erro e o formato podem variar dependendo da implementação do servidor de back-end.
Possível causa:
Esse erro ocorre se o servidor de back-end responder com o código de status 504 para a Apigee.
Observação: o código de erro
messaging.adaptors.http.flow.ErrorResponseCode não é retornado
como parte da mensagem de erro enviada aos aplicativos clientes. Isso acontece
porque esse código de erro é definido pela Apigee sempre que o servidor de back-end
responde com um erro e qualquer um dos códigos de status
4XX ou 5XX. Veja esse código de erro no monitoramento de APIs
ou no banco de dados de análise.
messaging.adaptors.http.flow.GatewayTimeout
Código de status HTTP:
504 Gateway Timeout
Mensagem de erro:
Gateway Timeout
Motivo:
TARGET_READ_TIMEOUT
Possível causa:
Esse erro ocorre se o servidor de back-end não responder ao processador de mensagens da Apigee no período de tempo limite de E/S configurado no processador de mensagens.
messaging.adaptors.http.flow.LengthRequired
Código de status HTTP:
411 Length Required
Mensagem de erro:
'Content-Length' is missing
Motivo:
CLIENT_REQUEST_CONTENT_LENGTH_REQUIRED
Possível causa:
Esse erro ocorrerá se o cabeçalho Content-Length não for transmitido pelo
aplicativo cliente como parte das solicitações HTTP POST e PUT
enviadas para a Apigee.
Observação: As solicitações com esse
erro não podem ser capturadas na ferramenta Trace, já que o processador de mensagens executa
essa validação em uma fase muito inicial, muito antes de processar a solicitação e
executar qualquer política no proxy de API.
Verifique se o aplicativo cliente sempre transmite o cabeçalho
Content-Length como parte das solicitações HTTP POST e
PUT enviadas para a Apigee. Exemplo:
curl -X POST https://HOSTALIAS/PATH -d '{"name": "abc"}' -H "Content-Length: 15"
Mesmo que você esteja passando um payload vazio com solicitações POST e PUT, verifique se o cabeçalho Content-Length: 0 foi transmitido. Exemplo:
curl -X POST https://HOSTALIAS/PATH -H "Content-Length: 0"
messaging.adaptors.http.flow.NoActiveTargets
Código de status HTTP:
503 Service Unavailable
Mensagem de erro:
The Service is temporarily unavailable
Motivo:
TARGET_HEALTHCHECK_CONNECT_TIMEOUT
TARGET_HEALTHCHECK_CONNECTION_REFUSED
TARGET_HEALTHCHECK_HTTPS_REQUEST_OVER_HTTP
TARGET_HEALTHCHECK_UNEXPECTED_EOF
Possível causa:
Esse erro ocorre em um dos seguintes cenários,
se você estiver usando o
TargetServer na Apigee:
A resolução incorreta de DNS do host do servidor de back-end
pelo servidor de autorização personalizado resultou em endereços IP incorretos que levam a
erros de conexão.
Erros de tempo limite de conexão devido a:
A restrição do firewall no servidor de back-end impede que a Apigee se conecte ao servidor de back-end.
Problemas de conectividade de rede entre a Apigee
e o servidor de back-end.
O host especificado no TargetServer está incorreto ou tem caracteres indesejados (como um espaço).
Esse erro também poderá ocorrer se as verificações de integridade configuradas para monitorar
a verificação dos servidores de destino falharem.
messaging.adaptors.http.flow.RequestTimeOut
Código de status HTTP:
408 Request Timeout
Mensagem de erro:
Request timed out
Motivo:
CLIENT_READ_TIMEOUT
Possível causa:
Esse erro ocorre se o processador de mensagens da Apigee não receber o
payload de solicitação do aplicativo cliente para o
tempo limite de E/S configurado no componente Processador de mensagens.
Correção
Verifique se o aplicativo cliente envia o payload da solicitação no período de tempo limite de E/S configurado no componente Processador de mensagens da Apigee.
messaging.adaptors.http.flow.ServiceUnavailable
Código de status HTTP:
503 Service Unavailable
Mensagem de erro:
The Service is temporarily unavailable
Motivo:
TARGET_CONNECT_TIMEOUT
TARGET_WRITE_BROKEN_PIPE
TARGET_WRITE_CONNECTION_RESET_BY_PEER
TARGET_CONNECT_CONNECTION_REFUSED
Possível causa:
Esse erro ocorre em um dos seguintes cenários::
A resolução incorreta de DNS do host do servidor de back-end
pelo servidor de autorização personalizado resultou em endereços IP incorretos que levam
a erros de conexão.
Erros de tempo limite de conexão devido a:
A restrição do firewall no servidor de back-end impede que a Apigee se conecte ao servidor de back-end.
Problemas de conectividade de rede entre a Apigee e o
servidor de back-end.
O host do servidor de destino especificado no endpoint de destino está incorreto ou tem caracteres indesejados, como espaço.
Esse erro também poderá ocorrer se o servidor de back-end fechar a conexão prematuramente enquanto o processador de mensagens ainda estiver enviando o payload da solicitação ao servidor de back-end.
messaging.adaptors.http.flow.SslHandshakeFailed
Código de status HTTP:
503 Service Unavailable
Mensagem de erro:
SSL Handshake failed {error_message}
Possível causa:
Esse erro ocorre durante o processo de handshake de SSL entre o processador de mensagens da Apigee e o servidor de back-end se:
O repositório de confiança do processador de mensagens da Apigee:
Contém uma cadeia de certificados que não corresponde à cadeia de certificados completa do servidor de back-end
OU
Não contém a cadeia de certificados completa do servidor de back-end
A cadeia de certificados apresentada pelo servidor de back-end:
Contém um nome de domínio totalmente qualificado (FQDN) que não corresponde ao
nome de host especificado no endpoint de destino
OU
Contém uma cadeia de certificados incorreta/incompleta
TargetServer não está configurado corretamente para suportar conexões TLS/SSL
na Apigee.
O servidor de back-end pode encerrar a conexão abruptamente,
enquanto a Apigee aguarda uma resposta do servidor de back-end.
Mantenha os tempos limite ativos ativados configurados incorretamente na Apigee e
no servidor de back-end.
messaging.runtime.*
messaging.runtime.RouteFailed
Código de status HTTP:
500 Internal Server Error
Mensagem de erro:
Unable to route the message to a TargetEndpoint
Possível causa:
Esse erro ocorre se a Apigee não puder encaminhar a solicitação para nenhum dos
TargetEndpoints porque:
Não há uma condição de regra de rota (<RouteRule>) que
corresponda à solicitação em um proxy
AND
Não há uma regra de rota padrão definida no ProxyEndpoint
(ou seja, <RouteRule> sem condição)
Correção
Para resolver esse erro, siga estas instruções:
Revise as regras de rota definidas no ProxyEndpoint e modifique para garantir que
haja pelo menos uma condição de regra de rota que corresponda à sua solicitação.
É uma boa prática definir uma regra de rota padrão sem condição quando você tem várias RouteRules.
Certifique-se de que a regra de rota padrão esteja definida por último na lista
de rotas condicionais porque as regras são avaliadas de cima para baixo no ProxyEndpoint.
Para saber mais sobre como definir condições <RouteRule> em um ProxyEndpoint, consulte
Destinos condicionais.
protocol.http.* - Caused due to bad request
protocol.http.BadFormData
Código de status HTTP:
500 Internal Server Error
Mensagem de erro:
Bad Form Data
Possível causa:
Esse erro ocorrerá se e somente se todas as condições a seguir forem satisfeitas:
A solicitação HTTP enviada pelo cliente à Apigee
contém:
Content-Type: application/x-www-form-urlencoded,
e
Dados de formulário com o sinal de porcentagem (%) ou o sinal de porcentagem (%) seguido de caracteres hexadecimais inválidos que não são permitidos de acordo com
Forms: seção 17.13.4.1.
O proxy de API na Apigee lê os parâmetros de formulário específicos que contêm os caracteres não permitidos usando a política ExtractVariables ou AttributionMessage no fluxo de solicitação.
protocol.http.DuplicateHeader
Código de status HTTP:
400 Bad Request
Mensagem de erro:
Duplicate Header "{header_name}"
Possível causa:
Esse erro ocorre quando um cabeçalho HTTP específico que não pode ter cópias
na Apigee aparece mais de uma vez com valores iguais ou diferentes como parte da
solicitação HTTP enviada pelo aplicativo cliente para a Apigee.
Verifique se a solicitação HTTP enviada pelo aplicativo cliente para a Apigee sempre contém um nome de cabeçalho válido de acordo com o
RFC 7230, seção 3.2: campos de cabeçalho.
protocol.http.HeaderNameWithNonAsciiChar
Código de status HTTP:
400 Bad Request
Mensagem de erro:
Header {header_name} contains non ascii character {character}
Possível causa:
Esse erro ocorre quando o nome do cabeçalho enviado como parte da solicitação HTTP
pelo aplicativo cliente para a Apigee contém caracteres não ASCII.
Header {header_name} contains invalid character {character}
Possível causa:
Esse erro ocorrerá se o nome do cabeçalho enviado como parte da solicitação HTTP
pelo aplicativo cliente para a Apigee tiver caracteres inválidos, como
igual (=), vírgula (,), ponto e vírgula (;), tab, CRLF, e um caractere de nova linha.
Em que: {hostname} é dinâmico, e seu valor
mudará em relação ao nome do host fornecido.
Motivo:
TARGET_CONNECT_HOST_NOT_REACHABLE
Possível causa:
Esse erro ocorrerá se o host do servidor de destino especificado estiver incorreto ou tiver caracteres indesejados, como espaço.
protocol.http.InvalidPath
Código de status HTTP:
400 Bad Request
Mensagem de erro:
Invalid path {path}
Possível causa:
Esse erro ocorre se o caminho no URL de solicitação HTTP enviado pelo aplicativo cliente
para a Apigee contiver caracteres que não são permitidos de acordo com a especificação
RFC 3986, seção 3.3: caminho.
Verifique se o caminho no URL de solicitação HTTP enviado pelo aplicativo
cliente para a
Apigee não contém nenhum caractere não permitido como
de acordo com a RFC 3986, seção 3.3: caminho.
protocol.http.TooBigBody
Código de status HTTP:
413 Request Entity Too Large
Mensagem de erro:
Body buffer overflow
Possível causa:
Esse erro ocorrerá se o tamanho do payload enviado pelo aplicativo cliente como parte da solicitação HTTP para a Apigee for maior que o limite permitido na Apigee.
O tamanho total de todos os cabeçalhos de solicitação enviados pelo aplicativo
cliente como parte da solicitação HTTP para a Apigee é maior do que o limite permitido
na Apigee.
Esse erro ocorrerá se o tamanho da linha de solicitação enviada pelo aplicativo cliente como parte da solicitação HTTP para a Apigee for maior que o limite permitido na Apigee.
Esse erro ocorrerá se o cabeçalho Content-Encoding enviado pelo cliente
como parte da resposta HTTP tiver um formato de codificação/payload não compatível com a
Apigee.
Este erro ocorrerá se o URL de solicitação do servidor de back-end, representado pela variável de fluxo target.url, contiver um caminho que começa com um ponto de interrogação (?) em vez de um encaminhamento barra (/), que é inválida.
Esse erro ocorre se o cabeçalho HTTP específico que não pode ter cópias
na Apigee aparece mais de uma vez com valores iguais ou diferentes como parte da
resposta HTTP enviada pelo servidor de back-end para a Apigee.
Verifique se a resposta HTTP enviada pelo servidor de back-end
à Apigee sempre contém um nome de cabeçalho válido de acordo com o
RFC 7230, seção 3.2: campos de cabeçalho.
protocol.http.EmptyPath
Código de status HTTP:
500 Internal Server Error
Mensagem de erro:
Request path cannot be empty
Possível causa:
Este erro ocorre se o URL de solicitação HTTP do servidor de back-end, representado pela variável de fluxo target.url, contiver um caminho vazio.
Header {header_name} contains non ascii character {character}
Possível causa:
Esse erro ocorrerá se o nome do cabeçalho enviado pelo servidor de back-end como parte da
resposta HTTP para o Apigee Edge
contiver caracteres não ASCII.
Header {header_name} contains invalid character {character}
Possível causa:
Esse erro ocorre quando o nome do cabeçalho enviado pelo servidor de back-end como parte da resposta HTTP contém caracteres inválidos, como igual (=), vírgula (,), ponto e vírgula (;), tab, CRLF e Nova linha.
Proxy refused to create tunnel with response status {status code}
Possível causa:
Esse erro ocorre durante a criação do túnel entre a Apigee e o
servidor de back-end pelo servidor proxy devido a firewall, ACL (lista de controle de acesso), problemas de
DNS, disponibilidade de disponibilidade do servidor de back-end etc.
Observação: o código de status na mensagem de erro
(faultstring) fornece a causa geral do problema.
protocol.http.Response306Reserved
Código de status HTTP:
502 Bad Gateway
Mensagem de erro:
Response Status code 306 is reserved, so can't be used.
Possível causa:
Esse erro ocorre se o servidor de back-end respondeu com o código de status 306 para a Apigee.
O código de status 306 foi definido em uma versão anterior da
especificação HTTP. De acordo com a especificação HTTP atual, esse código é
reservado e não pode ser usado.
Como o código de status 306 é reservado, verifique se
o servidor de back-end não usa esse código de status ao enviar uma
resposta à Apigee.
protocol.http.Response405WithoutAllowHeader
Código de status HTTP:
502 Bad Gateway
Mensagem de erro:
Received 405 Response without Allow Header
Possível causa:
O servidor de back-end responde com o código de status 405 Method Not Allowed sem o cabeçalho "Allow".
Especificação HTTP:
<aclass="external" l10n-attrs-original-order="href,class" l10n-encrypted-href="/PX9CewVbrdUzMVvoYtlcBAwphnODeWOvXeTBxkC1LyzyiBQ4MLFas/WazvgBhY96P0r5T0X7fdSVJ/HtE3Jxg==">
RFC 7231, seção 6.5.5: 405 método não permitido e
RFC 7231, seção 7.4.1: permitir</aclass="external">
protocol.http.ResponseWithBody
Código de status HTTP:
502 Bad Gateway
Mensagem de erro:
Received {status_code} Response with message body
Possível causa:
Esse erro ocorrerá se a resposta HTTP do servidor de back-end para a Apigee for
204 No Content ou
205 Reset Content, mas contiver o
corpo da resposta e/ou um ou mais dos seguintes cabeçalhos:
Esse erro ocorrerá se o tamanho do payload enviado pelo aplicativo cliente como parte da solicitação HTTP para a Apigee for maior que o limite permitido na Apigee.
Esse erro ocorre se o tamanho total de todos os cabeçalhos de resposta enviados pelo
servidor de back-end como parte da resposta HTTP à Apigee for maior que o
limite permitido na Apigee.
Esse erro ocorrerá se o tamanho da linha de resposta enviada pelo servidor de back-end como parte da resposta HTTP para a Apigee for maior que o limite permitido no Apigee Edge.
Esse erro ocorre se o cabeçalho Content-Encoding enviado pelo
servidor de back-end como parte da resposta HTTP contiver o formato de codificação/payload
que não é compatível com a Apigee.
KeyAlias {KeyAlias_name} is not found in
Keystore {Keystore_Name}
Possível causa:
Esse erro ocorre se o KeyAlias específico referenciado no TargetEndpoint
ou TargetServer não for encontrado no Keystore específico.
Correção
Verifique se o KeyAlias especificado em TargetEndpoint ou TargetServer faz parte do Keystore específico.
security.util.TrustStoreWithNoCertificates
Código de status HTTP:
500 Internal Server Error
Mensagem de erro:
TrustStore {truststore_name} has no certificates
Possível causa:
Esse erro ocorre se o Truststore específico referenciado no TargetEndpoint ou
TargetServer não contiver nenhum certificado.
Correção
Se você quiser validar o certificado do servidor de back-end e
quiser usar o Truststore em um TargetEndpoint ou TargetServer, verifique se o Truststore contém os certificados válidos do servidor de back-end.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2024-04-23 UTC."],[],[]]