Como lidar com falhas

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Muitas condições de erro podem surgir enquanto os proxies da API estão atendendo as solicitações dos aplicativos. Por exemplo, os proxies de API podem encontrar problemas de rede ao se comunicar com serviços de back-end, aplicativos podem apresentar credenciais expiradas, mensagens de solicitação podem estar formatadas incorretamente e assim por diante.

Quando ocorre um erro depois que um aplicativo cliente chama um proxy de API, uma mensagem de erro é retornada ao cliente. Por padrão, o cliente recebe uma mensagem de erro criptiva frequentemente sem detalhes ou orientação. No entanto, se você quiser substituir mensagens de erro padrão por mensagens personalizadas mais úteis e até mesmo aprimorá-las com cabeçalhos HTTP adicionais, será necessário configurar o tratamento de falhas personalizado na Apigee.

O tratamento de falhas personalizado também permite que você adicione funcionalidades, como a geração de registros de mensagens, sempre que ocorrer um erro.

Antes de falar sobre a implementação de tratamento de erros personalizados nos proxies de API, é útil entender como os erros ocorrem e como os proxies de API reagem a eles.

Vídeos

Assista os vídeos abaixo para saber mais sobre como lidar com falhas.

Vídeo Descrição
Introdução ao tratamento de falhas e fluxos de erros Saiba mais sobre o tratamento de falhas e o que acontece quando ocorre um erro em um proxy de API.
Solucionar falhas usando regras de falhas Saiba como lidar com falhas usando regras de falha.
Gerar falhas personalizadas usando a política RaiseFault Gerar falhas personalizadas durante o tempo de execução da API usando a política RaiseFault.
Definir regras de falha no proxy de API e nos endpoints de destino Defina regras de falha no proxy da API e nos endpoints de destino e entenda as diferenças.
Entenda a ordem de execução das regras de falha Entenda a ordem de execução das regras de falha no proxy de API e nos endpoints de destino.
Definir a regra de falha padrão Defina a regra de falha padrão para lidar com erros genéricos na API.

Como ocorrem os erros

Primeiro, vamos abordar como os erros ocorrem. Saber como os erros ocorrem ajuda você a planejar as diferentes situações em quer implementar o tratamento de erros personalizado.

Erros automáticos

Um proxy de API gera um erro automaticamente nas seguintes situações:

  • Uma política gera um erro. Por exemplo, se uma chamada de API envia uma chave expirada, a política VerifyAPIKey gera um erro automaticamente. ou se o número de chamadas de API exceder um determinado limite, a política de cotas ou a política de API do SpikeArrest gera um erro. Consulte a referência de erro de política para ver os tipos de erros que as políticas podem gerar.
  • Há um problema no fluxo de mensagens do proxy da API, como um erro de roteamento.
  • Há uma falha de back-end, como um erro HTTP devido a falhas no nível do protocolo, erros TLS/SSL ou um serviço de destino indisponível.
  • Há uma falha no nível do sistema, como uma exceção de falta de memória.

Para mais informações sobre esses erros, consulte taxonomia de falhas neste tópico.

Erros personalizados

Para situações em que não há um erro automático, pode ser útil gerar um erro personalizado. Por exemplo, se uma resposta contiver a palavra unavailable ou se o código de status HTTP for maior que 201. Para isso, adicione uma política RaiseFault para o local apropriado em um fluxo de proxy de API.

É possível adicionar uma política RaiseFault a um fluxo de proxy da API, assim como você faz com qualquer outra política. No exemplo de configuração de proxy a seguir, a política Raise-Fault-1 é anexada à resposta TargetEndpoint. Se a palavra unavailable estiver presente na resposta do serviço de destino, a política RaiseFault será executada e gerará um erro.

<TargetEndpoint name="default">
...
  <Response>
    <Step>
      <Name>Raise-Fault-1</Name>
      <Condition>message.content Like "*unavailable*"</Condition>
    </Step>
  </Response>

Isso é apenas para mostrar que é possível lançar erros personalizados. Temos mais detalhes sobre a política RaiseFault na seção FaultRules versus A política RaiseFault (em inglês).

Para mais exemplos, confira estas postagens da comunidade da Apigee:

O que os proxies de API fazem quando ocorrem erros

Veja o que acontece quando um proxy gera um erro.

Sair do pipeline de proxy

Quando um proxy de API encontra um erro, independentemente de como ele ocorre, ele sai do pipeline de fluxo normal, insere um estado de erro e retorna uma mensagem de erro ao aplicativo cliente. Depois que o proxy da API entra no estado de erro, ele não pode retornar o processamento para o pipeline de fluxo normal.

Por exemplo, suponha que um proxy de API tenha políticas na seguinte ordem na solicitação ProxyEndpoint:

  1. VerifyAPIKey
  2. Cota
  3. JSONtoXML

Se ocorrer um erro durante a verificação da chave de API, o proxy da API passará para um estado de erro. As políticas Quota e JSON para XML não são executadas, o proxy não segue para o TargetEndpoint, e uma mensagem de erro é retornada para o aplicativo cliente.

Verificar se há FaultRules

No estado do erro, os proxies da API também verificam a presença dos itens a seguir (na ordem) na configuração do proxy da API antes de retornar uma mensagem de erro padrão para o aplicativo cliente:

  1. Uma seção <FaultRules>, que contém a lógica para acionar mensagens de erro personalizadas (e outras políticas) com base em condições específicas definidas por você.
  2. Uma seção <DefaultFaultRule>, que aciona uma mensagem de erro padrão nas seguintes situações:
    • Nenhum <FaultRules> foi definido.
    • Nenhum <FaultRules> é executado.
    • O elemento <AlwaysEnforce> é definido como verdadeiro.

Em essência, o proxy de API oferece a oportunidade de retornar uma mensagem de erro personalizada e acionar outra lógica. Se o proxy não encontrar nenhuma dessas seções ou se elas existirem, mas nenhuma falha personalizada tiver sido acionada, o proxy enviará sua própria mensagem padrão gerada pela Apigee.

Exemplo simples de tratamento de falhas

Comece com um exemplo simples, em que uma chamada para um proxy de API não contém uma chave de API obrigatória. Por padrão, a resposta a seguir é retornada ao app cliente:

HTTP/1.1 401 Unauthorized
Date: Wed, 20 Jul 2016 19:19:32 GMT
Content-Type: application/json
Content-Length: 150
Connection: keep-alive
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

Os usuários da API podem descobrir a mensagem de erro, mas não podem. E muitos erros padrão são mais sutis e mais difíceis de decifrar.

Como um desenvolvedor de API, cabe a você alterar essa mensagem para atender às necessidades de quem receberá a mensagem de erro, seja um desenvolvedor de apps para iOS ou um grupo de teste interno com formato de mensagem de erro próprio. para a instalação.

Veja um exemplo básico de como você pode criar uma mensagem de erro personalizada para tratar desse erro. Isso requer 1) uma política que define a mensagem personalizada e 2) uma FaultRule que executa a política quando o proxy entra em um estado de erro.

1. Crie uma política que defina a mensagem personalizada

Primeiro, crie uma política que define a mensagem de erro personalizada. Use qualquer tipo de política, como uma política AssignMessage, que pode definir um payload e cabeçalhos HTTP opcionais, como o código do status e a frase de motivo. A política AssignMessage é ideal para isso. Ele permite que você controle o payload da mensagem, defina um código de status HTTP diferente, defina uma frase de razão HTTP diferente e adicione cabeçalhos HTTP.

Não é necessário anexar a política a um fluxo. crie conforme descrito emCriar a política.

Veja a seguir um exemplo de política AssignMessage que:

  • Retorna uma mensagem JSON.
  • Define um código de status HTTP (911, que é um código de status inexistente óbvio) para ilustrar a flexibilidade que você tem. O código de status aparece no cabeçalho HTTP.
  • Define uma frase de motivo HTTP (para substituir a frase de motivo Unauthorized padrão para esse erro de chave de API ausente). A frase do motivo aparece ao lado do código de status no cabeçalho HTTP.
  • Cria e preenche um novo cabeçalho HTTP chamado invalidKey.
<AssignMessage async="false" continueOnError="false" enabled="true" name="invalid-key-message">
    <DisplayName>Invalid key message</DisplayName>
    <Set>
        <Payload contentType="application/json">{"Citizen":"Where's your API key? I don't see it as a query parameter"}</Payload>
        <StatusCode>911</StatusCode>
    </Set>
    <Add>
        <Headers>
            <Header name="invalidKey">Invalid API key! Call the cops!</Header>
        </Headers>
    </Add>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Quando essa política for executada, a resposta ao app cliente será semelhante à seguinte. Compare-o com a resposta padrão mostrada anteriormente.

HTTP/1.1 911 Rejected by API Key Emergency Services
Date: Wed, 20 Jul 2016 18:42:36 GMT
Content-Type: application/json
Content-Length: 35
Connection: keep-alive
invalidKey: Invalid API key! Call the cops!
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"Citizen":"Where's your API key? I don't see it as a query parameter."}

Sim, é um pouco bobo, mas mostra o que é possível. Agora, pelo menos, o desenvolvedor que recebe a mensagem sabe que ele se esqueceu de incluir uma chave de API como um parâmetro de consulta.

Mas como essa política é executada? A próxima seção mostra você.

2. Crie a <FaultRule> que acionará a política

Nas seções <ProxyEndpoint> ou <TargetEndpoint> da configuração do proxy, você adicionará um bloco XML <FaultRules> que contém uma ou mais seções individuais <FaultRule>. Cada FaultRule representa um erro diferente que você quer processar. Neste exemplo simples, usaremos apenas uma FaultRule para mostrar do que ela é composta.

Também é necessário adicionar um <DefaultFaultRule> para fornecer uma mensagem de erro geral personalizada se nenhuma das FaultRules for executada.

Exemplo

<ProxyEndpoint name="default">
...
    <FaultRules>
       <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

Pontos principais

  • As FaultRules são definidas no ProxyEndpoint. Isso é importante Mais informações sobre como inserir FaultRules no ProxyEndpoint x TargetEndpoint mais tarde.
  • <Name>: o nome da política a ser executada. O nome vem do atributo name da política no elemento pai, conforme mostrado no exemplo da política anteriormente.

  • <Condition>: a Apigee avalia a condição e executa a política somente se a condição for verdadeira. Se houver várias FaultRules que são avaliadas como "true", a Apigee executará a primeira verdadeira. (Importantes: a ordem em que as FaultRules são avaliadas, de cima para baixo ou de baixo para cima, difere entre o TargetEndpoint e o ProxyEndpoint, conforme descrito na Várias lógicas FaultRules e lógica de execução.) Se você não incluir uma condição, a FaultRule será automaticamente verdadeira. Mas essa não é uma prática recomendada. Cada FaultRule precisa ter a própria condição.

  • <DefaultFaultRule>: se nenhuma FaultRule personalizada for executada, o <DefaultFaultRule> será executado, enviando uma mensagem personalizada mais genérica, em vez da mensagem padrão gerada pela Apigee. Um <DefaultFaultRule> também pode ter um <Condition>, mas, na maioria dos casos, você não incluirá um, porque quer que ele seja executado independentemente do último recurso.

    Normalmente, a DefaultFaultRule é usada para retornar uma mensagem de erro genérica de qualquer erro inesperado. Um exemplo seria uma mensagem contendo informações de contato para suporte técnico. Essa resposta padrão tem a finalidade dupla de fornecer informações amigáveis ao desenvolvedor e também ofuscar URLs de back-end ou outras informações que possam ser usadas para comprometer o sistema.

Várias lógicas FaultRules e de execução

Na seção Exemplo de tratamento de falhas simples, usamos um exemplo simples de uma única FaultRule e condição. Em um projeto de API real, com todos os possíveis erros que podem ocorrer, é provável que você tenha várias FaultRules e uma DefaultFaultRule em <ProxyEndpoint> e <TargetEndpoint>. No entanto, apenas uma falha FaultRule é executada quando um proxy da API entra em um estado de erro.

Esta seção descreve a lógica que a Apigee usa para lidar com FaultRules, desde como ela chega a uma única FaultRule para ser executada até como as condições de etapas internas são tratadas quando a FaultRule é acionada. Esta seção também fornece orientações sobre quando definir as FaultRules em <ProxyEndpoint> versus <TargetEndpoint> e descreve a relação entre FaultRules e a política RaiseFault.

Execução de FaultRules

Em resumo, veja a lógica usada pela Apigee quando um proxy de API entra em um estado de erro. Observe que há uma pequena diferença entre a avaliação das FaultRules no ProxyEndpoint em comparação com o TargetEndpoint.

  1. A Apigee avalia as FaultRules no ProxyEndpoint ou no TargetEndpoint, dependendo de onde o erro ocorreu:
    • EndpointProxy: a Apigee começa com o <FaultRule> na parte inferior no XML de configuração e vai até a parte superior, avaliando o <Condition> de cada <FaultRule> (a condição externa, e não as condições <Step> internas).
    • Endpoint de destino: a Apigee começa com a parte superior do <FaultRule> no XML de configuração e vai até a parte inferior, avaliando o <Condition> de cada <FaultRule> (a condição externa, e não as condições <Step> internas).
  2. Executa a primeira FaultRule com condição "true". Se uma FaultRule não tiver condição, ela será verdadeira por padrão.
    • Quando uma FaultRule é executada, todas as etapas dentro da FaultRule são avaliadas em ordem, de cima para baixo na configuração XML. As etapas sem condições são executadas automaticamente (as políticas são executadas) e as etapas que têm um <Condition> que se avalia e são executadas (as condições avaliadas em code não são executadas).

    • Se uma FaultRule for executada, mas nenhuma etapa da FaultRule for executada (porque as condições são avaliadas como code), a mensagem de erro padrão gerada pela Apigee será retornada ao aplicativo cliente. O <DefaultFaultRule> não é executado porque a Apigee já executou a própria FaultRule.

  3. Se nenhuma FaultRule for executada, a Apigee executará o <DefaultFaultRule>, se presente.

Veja a seguir exemplos com comentários in-line.

Execução de ProxyEndpoint

A avaliação de ProxyEndpoint FaultRules é de baixo para cima. Portanto, comece a ler na última FaultRule na amostra a seguir e a seguir. Observe a DefaultFaultRule por último.

<ProxyEndpoint name="default">
...
    <FaultRules>
<!-- 3. This FaultRule is automatically TRUE, because there's no outer
     condition. But because the FaultRule just below this got
     executed (bottom-to-top evaluation in a ProxyEndpoint), Apigee
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without 
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed. 
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
<FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 1. Because this is the ProxyEndpoint, Apigee looks at this FaultRule
     first. But let's say this FaultRule is FALSE. A policy did not 
     throw a FailedToResolveAPIKey error. Apigee moves UP to check
     the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. 
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Apigee has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

Execução de TargetEndpoint

A avaliação de TargetEndpoint FaultRules é de cima para baixo. Portanto, comece a ler na primeira FaultRule da amostra a seguir e siga as etapas abaixo. Observe a DefaultFaultRule por último.

<TargetEndpoint name="default">
...
    <FaultRules>
<!-- 1. Because this is the TargetEndpoint, Apigee looks at this FaultRule
     first. Let's say this FaultRule is FALSE. 
     A policy did not throw a FailedToResolveAPIKey error. 
     Apigee moves down to the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed. 
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
        <FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 3. This FaultRule is automatically TRUE, because there's no outer
     condition. But because the FaultRule just above this got
     executed (top-to-bottom evaluation in a TargetEndpoint), Apigee
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without 
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. 
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Apigee has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

Falha na ordem das regras

Como você pode ver no exemplo anterior, a ordem em que você coloca as FaultRules é importante dependendo se o erro ocorre no ProxyEndpoint em relação ao TargetEndpoint.

Exemplo:

Ordem de ProxyEndpoint Ordem de TargetEndpoint

No exemplo a seguir, como a avaliação é de baixo para cima, a FaultRule 3 é executada, o que significa que as FaultRules 2 e 1 não são avaliadas.

5. FaultRule 1: FALSE

4. FaultRule 2: TRUE

3. FaultRule 3: TRUE

2. FaultRule 4: FALSE

1. FaultRule: 5 FALSE

No exemplo a seguir, como a avaliação é de cima para baixo, a FaultRule 2 é executada, o que significa que as FaultRules 3, 4 e 5 não são avaliadas.

1. FaultRule 1: FALSE

2. FaultRule 2: TRUE

3. FaultRule 3: TRUE

4. FaultRule 4: FALSE

5. FaultRule: 5 FALSE

Políticas a serem incluídas

Você pode executar qualquer política de uma FaultRule colocando-a em Etapas. Por exemplo, é possível executar uma política AssignMessage para formatar uma resposta para o app cliente e, em seguida, registrar uma mensagem com a política MessageLogging. As políticas são executadas na ordem em que você as coloca (de cima para baixo no XML).

As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError)

O cabeçalho pode parecer que se repete, mas há uma nuance específica em relação a um erro de proxy que faz com que um proxy de API entre em um estado de erro ou não inserir um estado de erro: o continueOnError em uma política.

Para recapitular: um proxy de API avalia <FaultRules> e <DefaultFaultRule> somente se o proxy tiver entrado em um estado de erro. Isso significa que, mesmo que uma condição FaultRule seja avaliada como verdadeira, ela não será acionada se o proxy não estiver em um estado de erro.

No entanto, aqui está um exemplo de erro e o proxy não está entrando em um estado de erro. Em qualquer política, você pode definir um atributo no elemento pai chamado continueOnError. Esse atributo é muito importante em relação ao tratamento de falhas, porque determina se o proxy entra ou não em um estado de erro se a política falhar. Na maioria dos casos, convém manter a continueOnError="false" padrão, que coloca o proxy em um estado de erro se a política falhar e seu tratamento de erros personalizados será acionado. No entanto, se continueOnError="true" (por exemplo, se você não quiser que a chamada de um serviço pare a execução do proxy), o proxy não entrará em um estado de erro, se a política falhar e o proxy não examinará suas FaultRules.

Para informações sobre como registrar erros quando continueOnError="true", consulte Como lidar com falhas de política no fluxo atual.

Onde definir FaultRules: ProxyEndpoint ou TargetEndpoint

Quando um proxy de API apresenta um erro, o erro ocorre em <ProxyEndpoint> (solicitação de ou com resposta ao aplicativo cliente) ou em <TargetEndpoint> (solicitação para ou da resposta do serviço de destino). Sempre que esse erro ocorrer, a Apigee procurará por FaultRules.

Por exemplo, se um servidor de destino não estiver disponível (código de status HTTP 503), o proxy da API entrará em um estado de erro na resposta <TargetEndpoint>, e o fluxo de proxy de API normal não continuará no <ProxyEndpoint>. Se você tiver FaultRules definidas somente no <ProxyEndpoint>, elas não resolverão esse erro.

Veja outro exemplo. Se uma política RaiseFault na resposta <ProxyEndpoint> acionar um erro, uma FaultRule da <TargetEndpoint> não será executada.

FaultRules vs. a política RaiseFault

Regras de falha e a política RaiseFault podem aparecer de formas alternativas para realizar o tratamento de falhas e, em alguns aspectos, isso é verdade. Mas também funcionam juntas. Esta seção explica a relação entre as duas. Entender essa relação ajuda a projetar seu tratamento de falhas, especialmente se quiser usar as duas.

Para resumir:

  • As regras de falha são sempre avaliadas quando um proxy de API entra em um estado de erro.

  • A política RaiseFault é uma maneira de colocar um proxy de API em um estado de erro quando um erro não teria ocorrido de outra forma.

    Por exemplo, se você quiser gerar um erro se o código de status HTTP na resposta do serviço de destino for maior que 200, adicione uma política RaiseFault para seu fluxo de respostas. Ele será parecido com:

    <TargetEndpoint name="default">
    <PreFlow name="PreFlow">
...
        <Response>
            <Step>
                <Name>Raise-Fault-1</Name>
<!-- If the condition is true, the Raise-Fault-1 policy gets executed -->
                <Condition>(response.status.code GreaterThan "200")</Condition>
            </Step>
        </Response>

    A política RaiseFault também envia uma mensagem de erro para o app cliente.

O que acontece quando uma política RaiseFault aciona um erro, o que coloca o proxy em um estado de erro, o que pode executar uma falha? É aqui que as coisas podem ficar um pouco complicadas. Se a política RaiseFault retornar uma mensagem de erro e uma FaultRule for acionada e retornar uma mensagem de erro, o que será retornado para o app cliente?

  • Como a FaultRule ou a DefaultFaultRule é executada após a política RaiseFault, os dados de resposta da FaultRule vencem.
  • Os dados de resposta da política RaiseFault (código de status, frase de motivo ou payload da mensagem) serão usados se esses dados não forem definidos pela FaultRule ou DefaultFaultRule.
  • Se as políticas RaiseFault e FaultRule adicionarem cabeçalhos HTTP personalizados, ambos serão incluídos na resposta. Nomes de cabeçalho duplicados criam um cabeçalho com vários valores.

Observe um exemplo do que é definido por uma política RaiseFault e uma FaultRule e o que é retornado ao aplicativo cliente. Os exemplos são projetados para serem concisos, não para práticas recomendadas.

O que é definido por uma política RaiseFault e uma FaultRule.

O app cliente recebe:

Status Code: 468
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header:
  errorNote: woops,gremlins

<- A política de regras de falha define isso:

Status Code: [none] 
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header:
  errorNote: gremlins

<- RaiseFault define isso:

Status Code: 468
Reason Phrase: Can't do that
Payload: {"DOH!":"Try again."}
Header: 
  errorNote: woops

Condições de criação

As condições são a chave para a execução da FaultRule. Crie condições de FaultRule da mesma forma que faz para outras condições na Apigee, como no fluxo condicional ou nas condições RaiseFault.

Para colocar o restante desta seção no contexto, confira um exemplo de regra de falha que tem uma condição de FaultRule externa e uma condição de etapa interna.

<FaultRule name="invalid_key_rule">
    <Step>
        <Name>invalid-key-message</Name>
        <Condition>oauthV2.Verify-API-Key-1.failed = true</Condition>
    </Step>
    <Condition>fault.name = "FailedToResolveAPIKey"</Condition>
</FaultRule>

Variáveis específicas de erros de política

As variáveis fault.name e {policy_namespace}.{policy_name}.failed estão disponíveis quando uma política gera um erro.

fault.name

Quando uma política falhar, capture o erro em uma condição usando a variável fault.name. Exemplo:

<Condition>fault.name = "policy_error_name"</Condition>

O nome do erro é exibido na mensagem de erro padrão. Por exemplo, o nome da falha é FailedToResolveAPIKey. Nesse caso, uma variável de fluxo chamada fault.name é definida como o valor FailedToResolveAPIKey.

{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

Então, a condição seria assim:

<Condition>fault.name = "FailedToResolveAPIKey"</Condition>

Consulte a referência de erro de política para ver uma lista de erros de política.

{policy_namespace}.{policy_name}.failed

A variável *.failed estará disponível quando uma política falhar. Veja a seguir exemplos de variáveis *.failed para políticas diferentes. Para namespaces de políticas, consulte as variáveis de fluxo em cada tópico de referência da política.

Outras variáveis disponíveis

Quando um proxy de API entra em um estado de erro, as únicas variáveis disponíveis para uso nas condições são:

  • As variáveis da política que falharam.
  • As variáveis de mensagem HTTP que existem no ponto de falha. Por exemplo, se um erro for gerado na resposta, uma FaultRule em <TargetEndpoint> poderá usar dados HTTP response.status.code, message.content, error.content e assim por diante. Ou se uma política de cotas falhar, use a variável ratelimit.{quota_policy_name}.exceed.count. Use a ferramenta Debug e a referência de políticas para descobrir quais variáveis e dados HTTP estão disponíveis.

Mais informações

Práticas recomendadas para tratamento de falhas

O tratamento de falhas é uma importante tarefa de design arquitetônico para o desenvolvimento do proxy de API. É importante que você reserve um tempo para descobrir como e quando lidar com erros, determinar quais mensagens de erro dirão e projetar formatos de mensagem de erro. Depois (ou como) descobrir essas coisas, use essas práticas recomendadas para ajudar na implementação da manipulação de falhas.

Veja a seguir algumas práticas recomendadas para projetar e criar o tratamento de falhas:

  • Nas FaultRules, é possível especificar qualquer tipo de política. O padrão mais comum é usar a política "AssignMessage" para definir itens específicos na resposta de erro pendente. Também é possível usar o AssignMessage para definir variáveis usadas para outras finalidades, como variáveis referenciadas por políticas de geração de registros executadas no PostClientFlow ou no FlowHooks. Considere também registrar uma mensagem, por exemplo, com a política MessageLogging ou a política ServiceCallout, se quiser registrar erros específicos em condições de falha específicas.
  • Não especifique políticas RaiseFault como etapas em uma FaultRule. É melhor usar as políticas do AssignMessage para definir ou alterar elementos da mensagem, incluindo o payload, os cabeçalhos ou o código de status.
  • Para cada FaultRule, ou para todas, exceto a última FaultRule avaliada, forneça um <Condition> externo anexado como filho do elemento <FaultRule>. A condição de execução de uma FaultRule sem a condição explícita especificada será avaliada implicitamente como true. Um elemento <Condition> anexado como filho de um elemento <Step> não é usado para determinar se a condição de execução de FaultRule é avaliada como true ou falses As condições da etapa são avaliadas somente depois que a Apigee executa a FailRule que as contém. Em uma FaultRule, é comum ter várias etapas com políticas AssignMessage (ou outras), cada uma com uma condição Etapa.

  • Para processar erros em várias políticas do mesmo tipo (por exemplo, várias políticas de cota), crie uma FaultRule por erro de política que você provavelmente receberá e, em seguida, diferencie entre erros separados com condições anexadas a etapas. Por exemplo, crie uma FaultRule para processar um erro nas políticas de cotas, como QuotaViolation, e uma FaultRule separada para InvalidApiKeys Consulte a referência de erro de política para ver os erros de políticas À medida que você detecta outros erros que precisam ser tratados, pode voltar mais tarde e adicioná-los às FaultRules. Não há problema em ser iterativo, embora exija reimplantação de proxy. Essa abordagem permite que você identifique o mesmo tipo de erro, independentemente da política que a gera, o que torna seu XML FaultRules eficiente

    As condições da etapa interna fornecem um controle mais refinado. Por exemplo, se você estiver aplicando a cota individual de desenvolvedor e a cota global com duas políticas em seu fluxo de solicitação, defina a condição FaultRule outer para ser acionada em QuotaViolation (que é gerado quando a cota ultrapassa um dos casos). Em seguida, defina condições de etapa para avaliar as variáveis exceed.count nas duas políticas de cota. Somente o erro relevante é enviado ao cliente (sobreuso de cota global ou de cota global). Veja um exemplo dessa configuração:

    <FaultRule name="over_quota">
  <!-- This condition catches a QuotaViolation in *any* Quota policy -->
  <Condition>fault.name = "QuotaViolation"</Condition>
  <Step>
    <Name>AM-developer-over-quota-fault</Name>
    <Condition>ratelimit.developer-quota-policy.exceed.count GreaterThan 0</Condition>
  </Step>
  <Step>
    <Name>AM-global-over-quota-fault</Name>
    <Condition>ratelimit.global-quota-policy.exceed.count GreaterThan 0</Condition>
  </Step>
</FaultRule>

    Para ver outro exemplo, consulte esta discussão sobre o tratamento de falhas de política.

  • Para lidar com erros quando você estiver usando uma única política de um tipo, considere uma única regra de falha que seja executada quando essa política falhar e inclua várias etapas que mapeiam para cada erro possível. Isso mantém seu XML eficiente usando uma única FaultRule em vez de várias FaultRules (uma para cada tipo de erro). Por exemplo, você pode especificar que as diferentes etapas da política AssignMessage sejam executadas em condições distintas, como esta:

    <FaultRule name="raise-fault-3">
  <!-- This condition catches *any* error in the Verify-API-Key-1 policy. -->
  <Condition>oauthV2.Verify-API-Key-1.failed = "true"</Condition>
  <!-- This first step always executes, which handles errors you haven't mapped with inner conditions. -->
  <Step>
    <Name>AM-Generic-Key-Fault</Name>
  </Step>
  <Step>
    <Name>AM-API-Key-NotFound</Name>
    <Condition>fault.name = "FailedToResolveAPIKey"</Condition>
  </Step>
  <Step>
    <Name>AM-API-Key-Invalid</Name>
    <Condition>fault.name = "InvalidApiKey"</Condition>
  </Step>
</FaultRule>
  • Adicione FaultRules onde os erros ocorrerão (do lado do cliente <ProxyEndpoint> ou do lado do destino <TargetEndpoint>). Inclua FaultRules para cada política que aparece em cada local.
  • Ao usar políticas RaiseFault em conjunto com FaultRules, coordene os dados de resposta que são retornados de volta à política RaiseFault e à FaultRule. Por exemplo, se você tiver uma política RaiseFault que define o código de status HTTP, não configure também uma etapa AssignMessage em uma FaultRule que redefine o código. O pior que pode acontecer é que o código de status padrão é retornado ao app cliente.

  • O elemento <DefaultFaultRule> complementa o elemento <FaultRules> para oferecer mais controle sobre as políticas que o proxy executa quando processa um estado de falha. Se você especificar um <DefaultFaultRule>, ele será executado se uma ou ambas as condições a seguir forem verdadeiras:

    • Nenhuma outra FaultRule foi executada. Um caso especial aqui é se não houver nenhum elemento <FaultRules> configurado.
    • Se o elemento filho <AlwaysEnforce> do <DefaultFaultRule> for verdadeiro.

    Também é possível especificar um elemento <Condition> em um <DefaultFaultRule>. É possível fazer isso para excluir a execução com base em algum estado da solicitação ou mensagem de erro pendente, por exemplo, se um cabeçalho específico estiver presente ou ausente.

    Use um <DefaultFaultRule> com <AlwaysEnforce> definido como true, se você tiver uma ou mais políticas que você quer que o proxy sempre execute, sem importar se uma FaultRule anterior tem executada. Um cenário possível: suponha que você queira injetar um cabeçalho na resposta em todos os casos, se a solicitação de proxy resultou em uma falha ou se a falha foi processada anteriormente. Depois, você anexaria uma política AssignMessage apropriada na seção <PostFlow>/<Response> e também anexaria a mesma política no <DefaultFaultRule> com <AlwaysEnforce> definido como true.

Padrão para manipulação de falhas centralizada e reutilizável

Um padrão de tratamento de erros para proxies da Apigee descreve um padrão para o processamento centralizado de falhas sem duplicação de código.

Criar regras de falha

Para adicionar uma FaultRule, edite a configuração XML do ProxyEndpoint ou TargetEndpoint. Use a IU da Apigee para fazer essa edição no painel Code da visualização Develop de um proxy de API ou edite o arquivo XML que define o ProxyEndpoint ou TargetEndpoint.

Se você criar FaultRules na interface da Apigee, primeiro crie as políticas que quer executar e adicione-as à configuração da FaultRule. Você verá um erro na IU se tentar salvar uma FaultRule que faz referência a uma política que ainda não foi criada.

Como adicionar políticas a uma FaultRule

Embora você possa colocar qualquer política na FaultRule, geralmente é usada a política AssignMessage para gerar uma mensagem de resposta personalizada para uma condição de erro. O AssignMessage permite configurar uma resposta HTTP com payload, código de status HTTP, cabeçalhos e elementos de frase de motivo.

O exemplo abaixo mostra uma configuração de Política AssignMessage típica:

<AssignMessage name="AM-Invalid-Key">
  <Set>
      <Payload contentType="text/plain">That is an error.</Payload>
      <StatusCode>401</StatusCode>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Observe que ele não especifica um elemento <AssignTo>. Isso significa que ele será atribuído à mensagem ambiente, dependendo de onde a política estiver anexada.

Agora você pode usar essa política na sua FaultRule. Observe como você menciona a política AssignMessage por nome na FaultRule:

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>AM-Invalid-Key</Name>
      </Step>
      <Condition>fault.name = "InvalidApiKey"</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

Quando você implanta a configuração acima, o proxy da API executa a política AssignMessage chamada AM-Invalid-Key sempre que um aplicativo apresenta uma chave de API inválida.

Você pode executar várias políticas em uma FaultRule, como mostra o exemplo a seguir:

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>AM-Invalid-Key</Name>
      </Step>
      <Step>
        <Name>policy2</Name>
      </Step>
      <Step>
        <Name>policy3</Name>
      </Step>
      <Condition>fault.name = "InvalidApiKey"</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

As políticas são executadas na ordem definida. Por exemplo, você pode usar a política MessageLogging, a política ExtractVariables, a política AssignMessage ou qualquer outra política na FaultRule. Observe que o processamento de FaultRule será interrompido imediatamente se uma destas situações ocorrer:

  • Qualquer política na FaultRule causa um erro
  • Qualquer uma das políticas na FaultRule é do tipo RaiseFault

Definir a mensagem de erro personalizada retornada de uma FaultRule

Como prática recomendada, defina respostas de erro claras das APIs. Dessa forma, você fornece informações consistentes e úteis para seus clientes.

O exemplo a seguir de política AssignMessage usa as tags <Payload> e <StatusCode> para definir a resposta de erro personalizada enviada ao cliente em um erro InvalidApiKey (consulte o exemplo FaultRules anterior).

<AssignMessage name="AM-Invalid-Key">
  <Set>
    <Payload contentType="text/plain">You have attempted to access a resource without the correct authorization.
       Contact support at support@mycompany.com.</Payload>
    <StatusCode>401</StatusCode>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Essa resposta inclui:

  • O payload que contém a mensagem de erro e um endereço de e-mail para entrar em contato com o suporte.
  • Código de status HTTP retornado na resposta.
  • A frase de motivo, que é uma breve descrição do erro.

Como criar uma DefaultFaultRule

Uma DefaultFaultRule atua como um gerenciador de exceções para qualquer erro não processado explicitamente por outra falha com FaultRule. Se as condições de todas as FaultRules não corresponderem ao erro, a DefaultFaultRule processará o erro. Ative o tratamento de falhas padrão adicionando a tag <DefaultFaultRule> como um elemento filho de um ProxyEndpoint ou TargetEndpoint.

Por exemplo, a configuração de TargetEndpoint abaixo define uma DefaultFaultRule que invoca uma política chamada AM-Return-Generic-Error:

<TargetEndpoint name="default">
  ...
  <FaultRules>
    ...
  </FaultRules>

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>AM-Return-Generic-Error</Name>
    </Step>
  </DefaultFaultRule>

  <HTTPTargetConnection>
    <URL>https://mytarget.example.net</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Normalmente, a DefaultFaultRule é usada para retornar uma mensagem de erro genérica para qualquer erro inesperado, como uma mensagem que contenha dados de contato para suporte técnico. Essa resposta padrão tem a finalidade dupla de fornecer informações amigáveis ao desenvolvedor e também ofuscar URLs de back-end ou outras informações que podem ser usadas para comprometer o sistema.

Por exemplo, você define a seguinte política AssignMessage para retornar um erro genérico:

<AssignMessage name="AM-Return-Generic-Error">
  <Set>
    <Payload type="text/plain">SERVICE UNAVAILABLE. PLEASE CONTACT SUPPORT: support@company.com.</Payload>
  </Set>
</AssignMessage>

Inclua o elemento <AlwaysEnforce> na tag <DefaultFaultRule> para executar a DefaultFaultRule para cada erro, mesmo se outra FaultRule já tiver sido executada. A DefaultFaultRule é sempre a última falha de falha a ser executada:

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>AM-Return-Generic-Error</Name>
    </Step>
    <AlwaysEnforce>true</AlwaysEnforce>
  </DefaultFaultRule>

Um dos usos da DefaultFaultRule é determinar o tipo de erro que ocorre quando você não o determina. Por exemplo, se o proxy de API estiver falhando devido a um erro que você não consegue determinar, use a DefaultFaultRule para invocar a seguinte política AssignMessage. Esta política grava o valor fault.name em um cabeçalho chamado Unhandled-Fault na resposta:

<AssignMessage name="AM-Set-Fault-Header">
  <Set>
    <Headers>
      <Header name="Unhandled-Fault">{fault.name}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

É possível visualizar o cabeçalho na ferramenta Debug ou na resposta para ver o que causou o erro.

Como adicionar a geração de registros de mensagens ao PostClientFlow

O PostClientFlow é o único fluxo que é executado depois que o proxy entra no estado de erro. Somente a política MessageLogging pode ser anexada a esse fluxo, que é executada depois que a resposta é enviada de volta ao cliente. Embora a anexação da política MessageLogging a esse fluxo não seja tecnicamente um tratamento de erros, é possível usá-la para registrar informações no caso de um erro. Como ele é executado, independentemente de o proxy ter êxito ou falha, é possível colocar as políticas de Registro de mensagens no PostClientFlow e garantir que elas sejam sempre executadas.

Como lidar com falhas de política no fluxo atual

Todos os exemplos mostrados até agora usam uma FaultRule no ProxyEndpoint ou TargetEndpoint para lidar com erros de política como parte do estado do erro. Isso ocorre porque o valor padrão do elemento continueOnError de uma política é false, o que significa que, quando ocorre um erro em uma política, o controle é direcionado para o estado do erro. Quando estiver no estado de erro, não será possível retornar o controle ao pipeline normal e você normalmente retornará alguma mensagem de erro para o aplicativo de chamada.

No entanto, se você definir o elemento continueOnError como true para uma política, o controle permanecerá no fluxo atual e a próxima política no pipeline será executada após a política que causou o erro. A vantagem de lidar com o erro no fluxo atual é que você pode ter uma maneira de se recuperar do erro para concluir o processamento da solicitação.

Veja a seguir uma política VerifyAPIKey chamada verify-api-key com o elemento continueOnError definido como true:.

<VerifyAPIKey continueOnError="true" name="verify-api-key">
  <DisplayName>Verify API Key</DisplayName>
  <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

Se a chave de API estiver ausente ou for inválida, a política VerifyAPIKey definirá a variável oauthV2.verify-api-key.failed como true, mas o processamento continuará no fluxo atual.

Em seguida, adicione a política VerifyAPIKey como uma etapa no PreFlow do ProxyEndpoint:

<ProxyEndpoint name="default">
  ...
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>verify-api-key</Name>
      </Step>
      <Step>
        <Name>FaultInFlow</Name>
        <Condition>oauthV2.verify-api-key.failed = "true"</Condition>
      </Step>
    </Request>
    <Response/>
  </PreFlow>      
</ProxyEndpoint>

Observe como a próxima etapa no PreFlow usa uma condição para testar a existência de um erro. Se ocorrer um erro na política VerifAPIKey, a política chamada FaultInFlow será executada. Caso contrário, a política FaultInFlow será ignorada. A política FaultInFlow pode fazer muitas coisas, como registrar o erro, tentar corrigi-lo ou executar outra ação.

Como acionar um erro usando a política RaiseFault

Você pode usar a política RaiseFault a qualquer momento em um fluxo para acionar um erro. Quando uma política RaiseFault é executada, ela encerra o fluxo atual e transfere o controle para o estado de erro.

Um uso da política RaiseFault é testar uma condição específica que outra política talvez não detecte. No exemplo acima, você adicionou uma tag <Condition> a uma tag <Step> do PreFlow que causou a execução da política FaultInFlow se a condição fosse atendida. Se FaultInFlow for uma política RaiseFault, controle as transferências para o estado de erro. Ou você pode inserir uma política RaiseFault em um fluxo para depurar e testar suas FaultRules.

Quando uma política RaiseFault acionar um erro, você poderá usar a seguinte FaultRule e a condição para processá-la:

<FaultRule name="raisefault_rule">
  <Step>
    <Name>POLICY-NAME-HERE</Name>
  </Step>
  <Condition>fault.name = "RaiseFault"</Condition>
</FaultRule>

Observe que a condição testa uma falha chamada RaiseFault. A política RaiseFault sempre define o valor de fault.name como RaiseFault. Também é possível definir variáveis personalizadas em uma política RaiseFault. Se você fizer isso, poderá testar essas variáveis nos elementos Condição.

Tratamento personalizado de códigos de erros HTTP do servidor de destino

Os exemplos mostrados nas seções anteriores se aplicam a erros criados por políticas. No entanto, você também pode criar uma resposta personalizada para erros no nível do transporte, o que significa erros HTTP retornados do servidor de destino. Para controlar a resposta de um erro HTTP, configure um TargetEndpoint para processar códigos de resposta HTTP.

Por padrão, a Apigee trata os códigos de resposta HTTP no intervalo 1xx-3xx como sucesso, e os códigos de resposta HTTP no intervalo 4xx-5xx como failure. Isso significa que qualquer resposta do serviço de back-end com um código de resposta HTTP 4xx-5xx invoca automaticamente o estado de erro, que retorna uma mensagem de erro diretamente ao cliente solicitante.

Você pode criar gerenciadores personalizados para qualquer código de resposta HTTP. Por exemplo, não convém tratar todos os códigos de resposta HTTP no intervalo 4xx-5xx como "falha", mas apenas 5xx, ou você pode retornar mensagens de erro personalizadas para Códigos de resposta HTTP 400 e 500

No próximo exemplo, você usa a propriedade success.codes para configurar o TargetEndpoint para tratar os códigos de resposta HTTP 400 e 500 como bem-sucedidos, junto com os códigos HTTP padrão. Ao tratar esses códigos como um sucesso, o TargetEndpoint assume o processamento da mensagem de resposta, em vez de invocar o estado do erro:

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <Properties>
          <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Como você pode ver neste exemplo, é possível usar caracteres curinga para definir a propriedade success.codes como um intervalo de valores.

A definição da propriedade success.codes substitui os valores padrão. Portanto, se você quiser adicionar o código HTTP 400 à lista de códigos de sucesso padrão, defina esta propriedade como:

<Property name="success.codes">1xx,2xx,3xx,400</Property>

No entanto, se você quiser apenas que o código HTTP 400 seja tratado como um código de sucesso, defina a propriedade como:

<Property name="success.codes">400</Property>

Agora, é possível definir gerenciadores personalizados para os códigos de resposta HTTP 400 e 500 para retornar uma mensagem de resposta personalizada ao app solicitante. O seguinte TargetEndpoint usa a política chamada ReturnError para lidar com os códigos de resposta HTTP 400 e 500:

<TargetEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request/>
    <Response>
      <Step>
        <Name>ReturnError</Name>
        <Condition>(response.status.code = 400) or (response.status.code = 500)</Condition>
      </Step>
    </Response>
  </PreFlow>

  <HTTPTargetConnection>
    <Properties>
      <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Essa configuração de TargetEndpoint faz a política chamada ReturnError para processar a resposta sempre que o TargetEndpoint encontra um código de resposta HTTP de 400 OU 500.

Taxonomia de falhas

Os Serviços de API organizam falhas nas categorias e subcategorias a seguir.

Categoria Subcategoria Nome da falha Descrição
Mensagens Falhas que ocorrem durante o fluxo da mensagem (sem incluir falhas de política)
Falhas personalizadas {fault_name} Falhas explicitamente processadas pelo proxy de API usando a política RaiseFault
Códigos de resposta InternalServerError, NotFound Códigos de erro 5xx e 4xx
Falhas de roteamento NoRoutesMatched Falha ao selecionar um TargetEndpoint nomeado para uma solicitação
Falhas de classificação NotFound Falhas causadas por um URI de solicitação que não corresponde a nenhum BasePath para nenhuma configuração ProxyEndpoint (ou seja, nenhum proxy de API corresponde ao URL na solicitação do app cliente)
Transporte Erros no nível de transporte HTTP
Conectividade ConnectionRefused, ConnectionReset, ConnectionTimeout Falhas ao estabelecer conexões no nível da rede ou do transporte
Validações de solicitação ContentLengthMissing, HostHeaderMissing As falhas ocorrem durante as verificações semânticas em todas as solicitações
Validações de resposta Falhas durante verificações de semântica em cada resposta
Erros de E/S SSLHandshakeError, ReadTimeout, ReadError, WriteTimeout, WriteError, ChunkError Erros de leitura/gravação em endpoints de cliente ou de destino, tempos limite, erros TLS/SSL e erros em blocos
Sistema Erros de tempo de execução indefinidos
Memória OutOfMemory, GCOverLimit Falhas relacionadas à memória
Conversa RogueTaskTerminated Falhas, como o encerramento de tarefas em andamento
Política As falhas de cada tipo de política são definidas na Referência da política.

Um erro é sempre acompanhado por uma descrição do texto do motivo da falha. Quando o sistema gera uma falha, um conjunto de atributos é preenchido para ajudar na solução de problemas. Uma falha inclui as seguintes informações:

  • Motivo
  • Atributos personalizados definidos pelo usuário