Processamento de falhas

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Podem surgir muitas condições de erro enquanto os proxies de API processam pedidos de apps. Por exemplo, os proxies de API podem encontrar problemas de rede ao comunicar com os serviços de back-end, as apps podem apresentar credenciais expiradas, as mensagens de pedido podem estar formatadas incorretamente, e assim sucessivamente.

Quando ocorre um erro depois de uma app cliente chamar um proxy de API, é devolvida uma mensagem de erro ao cliente. Por predefinição, o cliente recebe uma mensagem de erro frequentemente enigmática sem detalhes nem orientações. No entanto, se quiser substituir as mensagens de erro predefinidas por mensagens personalizadas mais úteis e até enriquecê-las com elementos como cabeçalhos HTTP adicionais, tem de configurar o processamento de falhas personalizado no Apigee.

O processamento de falhas personalizado também permite adicionar funcionalidades, como o registo de mensagens sempre que ocorre um erro.

Antes de falarmos sobre a implementação do processamento de erros personalizado nos seus proxies de API, é útil compreender como ocorrem os erros e como os proxies de API reagem a eles.

Vídeos

Veja os vídeos seguintes para saber mais sobre o processamento de falhas.

Vídeo Descrição
Introdução ao processamento de falhas e fluxos de erros Saiba mais sobre o processamento de falhas e o que acontece quando ocorre um erro num proxy de API.
Resolva falhas com regras de falhas Saiba como processar falhas através de regras de falhas.
Gere falhas personalizadas através da política RaiseFault Gere falhas personalizadas durante a execução da API através da política RaiseFault.
Defina regras de falhas nos pontos finais de destino e no proxy de API Defina regras de falhas no proxy de API e nos pontos finais de destino, e compreenda as diferenças.
Compreenda a ordem de execução das regras de falhas Compreenda a ordem de execução das regras de falhas no proxy de API e nos endpoints de destino.
Defina a regra predefinida Defina a regra de falha predefinida para processar erros genéricos na sua API.

Como ocorrem os erros

Primeiro, vamos abordar simplesmente como ocorrem os erros. Saber como ocorrem os erros ajuda a planear as diferentes situações em que quer implementar o processamento 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 API enviar uma chave expirada, a política VerifyAPIKey gera automaticamente um erro. Em alternativa, se o número de chamadas API exceder um determinado limite, a política de quota ou a política SpikeArrest gera um erro. (Consulte a referência de erros de políticas para ver os tipos de erros que as políticas podem gerar).
  • Existe um problema no fluxo de mensagens do proxy da API, como um erro de encaminhamento.
  • Ocorreu uma falha no back-end, como um erro de HTTP devido a falhas ao nível do protocolo, erros de TLS/SSL ou um serviço de destino indisponível.
  • Existe uma falha ao nível do sistema, como uma exceção de falta de memória.

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

Erros personalizados

Para situações em que não existe um erro automático, pode querer gerar um erro personalizado; por exemplo, se uma resposta contiver a palavra unavailable ou se o código de estado HTTP for superior a 201. Para isso, adicione uma política RaiseFault ao local adequado num fluxo de proxy de API.

Pode adicionar uma política RaiseFault a um fluxo de proxy de API da mesma forma que adiciona qualquer outra política. No exemplo de configuração de proxy seguinte, a política Raise-Fault-1 está anexada à resposta TargetEndpoint. Se a palavra unavailable estiver presente na resposta do serviço de destino, a política RaiseFault é executada e gera um erro.

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

Isto serve apenas para mostrar que pode gerar erros personalizados. Entramos em mais detalhes sobre a política RaiseFault na secção FaultRules vs. a política RaiseFault.

Para mais exemplos, consulte estas publicações da comunidade do Apigee:

O que os proxies de API fazem quando ocorrem erros

Eis o que acontece quando um proxy gera um erro.

Saia da pipeline de proxy

Quando um proxy de API encontra um erro, independentemente de como ocorre, sai do pipeline de fluxo normal, entra num estado de erro e devolve uma mensagem de erro à app cliente. Assim que o proxy de API entra no estado de erro, não pode devolver o processamento ao pipeline de fluxo normal.

Por exemplo, suponha que um proxy de API tem políticas pela seguinte ordem no pedido ProxyEndpoint:

  1. Valide a chave da API
  2. Quota
  3. JSON para XML

Se ocorrer um erro durante a validação da chave da API, o proxy de API passa para um estado de erro. As políticas de quota e JSON para XML não são executadas, o proxy não avança para o TargetEndpoint e é devolvida uma mensagem de erro à app cliente.

Verifique se existem FaultRules

No estado de erro, os proxies de API também verificam a presença do seguinte (por ordem) na configuração do proxy de API antes de devolver uma mensagem de erro predefinida à app cliente:

  1. Uma secçã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 que define.
  2. Uma secção <DefaultFaultRule>, que aciona uma mensagem de erro predefinida nas seguintes situações:
    • Não estão definidos <FaultRules>.
    • Nenhuma <FaultRules> existente é executada.
    • O elemento <AlwaysEnforce> está definido como verdadeiro.

Essencialmente, o proxy da API dá-lhe a oportunidade de devolver uma mensagem de erro personalizada e acionar outra lógica. Se o proxy não encontrar nenhuma dessas secções ou se existirem, mas não tiver sido acionado nenhum erro personalizado, o proxy envia a sua própria mensagem predefinida gerada pelo Apigee.

Exemplo de processamento de falhas simples

Vamos começar com um exemplo simples, em que uma chamada para um proxy de API não contém uma chave de API obrigatória. Por predefinição, segue-se a resposta devolvida à 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 utilizadores da API podem conseguir descobrir a mensagem de erro, mas também podem não conseguir. Além disso, muitos erros predefinidos são mais subtis e difíceis de descifrar.

Como programador de APIs, é da sua responsabilidade alterar esta mensagem para satisfazer as necessidades de quem vai receber a mensagem de erro, quer seja um programador de apps iOS ou um grupo de testes interno que tenha os seus próprios requisitos de formato de mensagens de erro.

Segue-se um exemplo básico de como criar uma mensagem de erro personalizada para processar este erro. Isto requer 1) uma política que defina a mensagem personalizada e 2) uma FaultRule que execute a política quando o proxy entra num estado de erro.

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

Primeiro, crie uma política que defina a mensagem de erro personalizada. Pode usar qualquer tipo de política, como uma política AssignMessage, que possa definir uma carga útil e cabeçalhos HTTP opcionais, como o código de estado. A política AssignMessage é ideal para este efeito. Permite-lhe controlar a carga útil da mensagem, definir um código de estado HTTP diferente e adicionar cabeçalhos HTTP.

Não precisa de anexar a política a um fluxo. Basta criá-la, conforme descrito em Crie a política.

Segue-se um exemplo de uma política AssignMessage que:

  • Devolve uma mensagem JSON.
  • Define um código de estado HTTP (911, que é um código de estado obviamente inexistente apenas para ilustrar a flexibilidade que tem). O código de estado aparece no cabeçalho HTTP.
  • Cria e preenche um novo cabeçalho HTTP denominado 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!</Header>
        </Headers>
    </Add>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Quando esta política é executada, a resposta à app cliente tem o seguinte aspeto. Compare-a com a resposta predefinida apresentada 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!
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 ridículo, mas mostra o que é possível. Pelo menos, agora, o programador que recebe a mensagem sabe que se esqueceu de incluir uma chave da API como parâmetro de consulta.

Mas como é que esta política é executada? A secção seguinte mostra-lhe.

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

Nas secções <ProxyEndpoint> ou <TargetEndpoint> da configuração do proxy, adiciona um bloco XML <FaultRules> que contém uma ou mais secções <FaultRule> individuais. Cada FaultRule representa um erro diferente que quer processar. Neste exemplo simples, vamos usar apenas uma FaultRule para lhe mostrar do que é composta.

Também deve adicionar um elemento <DefaultFaultRule> para fornecer uma mensagem de erro geral personalizada se nenhuma das suas 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-chave:

  • As FaultRules estão definidas no ProxyEndpoint. Isto é importante. Mais informações sobre a colocação de FaultRules no ProxyEndpoint vs. TargetEndpoint mais tarde.
  • <Name>: o nome da política a executar. O nome vem do atributo name da política no elemento principal, conforme mostrado no exemplo de política anterior.

  • <Condition>: o Apigee avalia a condição e executa a política apenas se a condição for verdadeira. Se existirem várias FaultRules que são avaliadas como verdadeiras, o Apigee executa a primeira que é verdadeira. (Importante: 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 secção Várias FaultRules e lógica de execução.) Se não incluir uma condição, a FaultRule é automaticamente verdadeira. No entanto, não é uma prática recomendada. Cada FaultRule deve ter a sua própria condição.

  • <DefaultFaultRule>: se não for executada nenhuma FaultRule personalizada, é executada a <DefaultFaultRule>, que envia uma mensagem personalizada mais genérica em vez da mensagem predefinida enigmática gerada pelo Apigee. Um <DefaultFaultRule> também pode ter um <Condition>, mas, na maioria dos casos, não inclui um, porque quer que seja executado independentemente do que acontecer como último recurso.

    Normalmente, a DefaultFaultRule é usada para devolver uma mensagem de erro genérica para qualquer erro inesperado. Um exemplo seria uma mensagem que contém informações de contacto para o apoio técnico. Esta resposta predefinida tem o duplo objetivo de fornecer informações de fácil utilização para os programadores e, ao mesmo tempo, ocultar URLs de back-end ou outras informações que possam ser usadas para comprometer o sistema.

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

Na secção Exemplo de processamento de falhas simples, usámos um exemplo simples de uma única FaultRule e condição. Num projeto de API do mundo real, com todos os erros possíveis que podem ocorrer, é provável que tenha várias FaultRules e uma DefaultFaultRule nos seus <ProxyEndpoint> e <TargetEndpoint>. No entanto, em última análise, apenas uma FaultRule é executada quando um proxy de API entra num estado de erro.

Esta secção descreve a lógica que o Apigee usa no processamento de FaultRules, desde a forma como chega a uma única FaultRule a executar até à forma como as condições dos passos internos são processadas quando a respetiva FaultRule é acionada. Esta secção também fornece orientações sobre quando definir FaultRules no elemento <ProxyEndpoint> vs. <TargetEndpoint> e descreve a relação entre FaultRules e a política RaiseFault.

Execução de FaultRules

Em resumo, aqui está a lógica que o Apigee usa quando um proxy de API entra num estado de erro. Tenha em atenção que existe uma ligeira diferença entre a avaliação de FaultRules no ProxyEndpoint e no TargetEndpoint.

  1. O Apigee avalia as FaultRules no ProxyEndpoint ou no TargetEndpoint, consoante o local onde ocorreu o erro:
    • ProxyEndpoint: o Apigee começa com o inferior <FaultRule> no XML de configuração e avança, avaliando o <Condition> de cada <FaultRule> (a condição externa e não as condições internas <Step>).
    • TargetEndpoint: o Apigee começa com o top <FaultRule> no XML de configuração e avança, avaliando o <Condition> de cada <FaultRule> (a condição exterior, não as condições interiores <Step>).
  2. Executa a FaultRule first cuja condição é verdadeira. Se uma FaultRule não tiver uma condição, é verdadeira por predefinição.
    • Quando uma FaultRule é executada, todos os Steps na FaultRule são avaliados por ordem, de cima para baixo na configuração XML. Os passos sem condições são executados automaticamente (as políticas são executadas) e os passos que têm um <Condition> que é avaliado como são executados (as condições que são avaliadas como code não são executadas).

    • Se uma FaultRule for executada, mas não forem executados passos na FaultRule (porque as respetivas condições são avaliadas como code), a mensagem de erro predefinida gerada pelo Apigee é devolvida à app cliente. A <DefaultFaultRule> não é executada, porque o Apigee já executou a respetiva FaultRule.

  3. Se não for executada nenhuma FaultRule, o Apigee executa o <DefaultFaultRule>, se estiver presente.

Seguem-se exemplos com comentários inline.

Execução de ProxyEndpoint

A avaliação das FaultRules do ProxyEndpoint é feita de baixo para cima. Por isso, comece a ler a última FaultRule no exemplo seguinte e continue até acima. Analise 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 das FaultRules de TargetEndpoint é feita de cima para baixo, por isso, comece a ler a primeira FaultRule no exemplo seguinte e continue até abaixo. Analise 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>

Ordem das regras de falha

Como pode ver no exemplo anterior, a ordem em que coloca as FaultRules é importante, dependendo se o erro ocorre no ProxyEndpoint ou no TargetEndpoint.

Por exemplo:

Ordem do ProxyEndpoint Ordem do TargetEndpoint

No exemplo seguinte, uma vez que 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 seguinte, uma vez que 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 incluir

Pode executar quaisquer políticas a partir de uma FaultRule colocando-as em Steps. Por exemplo, pode executar uma política AssignMessage para formatar uma resposta à app cliente e, em seguida, registar uma mensagem com a política MessageLogging. As políticas são executadas pela ordem em que as coloca (de cima para baixo no XML).

As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError)

O título pode parecer uma repetição, mas existe uma nuance específica a ter em atenção no que diz respeito a um erro de proxy que faz com que um proxy de API entre num estado de erro ou, melhor dizendo, não entre num estado de erro: o atributo continueOnError numa política.

Para recapitular: um proxy de API avalia <FaultRules> e <DefaultFaultRule> apenas se o proxy tiver entrado num estado de erro. Isto significa que, mesmo que uma condição FaultRule seja avaliada como verdadeira, não é acionada se o proxy não estiver num estado de erro.

No entanto, segue-se um exemplo de um erro que ocorre e o proxy não entra num estado de erro. Em qualquer política, pode definir um atributo no elemento principal denominado continueOnError. Esse atributo é muito importante no que diz respeito ao processamento de falhas, porque determina se o proxy entra ou não num estado de erro se a política falhar. Na maioria dos casos, é recomendável manter a predefinição continueOnError="false", que coloca o proxy num estado de erro se a política falhar, e o processamento de erros personalizado é acionado. No entanto, se continueOnError="true" (por exemplo, se não quiser que a falha de um Service Callout pare a execução do proxy), o proxy não entra num estado de erro se essa política falhar, e o proxy não tem em conta as suas FaultRules.

Para obter informações sobre o registo de erros quando continueOnError="true", consulte o artigo Processar falhas de políticas no fluxo atual.

Onde definir FaultRules: ProxyEndpoint ou TargetEndpoint

Quando um proxy de API tem um erro, o erro ocorre no <ProxyEndpoint> (pedido da ou resposta à app cliente) ou no <TargetEndpoint> (pedido ao ou resposta do serviço de destino). O Apigee procura FaultRules no local onde ocorre esse erro.

Por exemplo, se um servidor de destino não estiver disponível (código de estado HTTP 503), o proxy de API entra num estado de erro na resposta <TargetEndpoint> e o fluxo normal do proxy de API não continua para o <ProxyEndpoint>. Se tiver FaultRules definidas apenas no <ProxyEndpoint>, estas não processam esse erro.

Segue-se outro exemplo. Se uma política RaiseFault na resposta <ProxyEndpoint> acionar um erro, não é executada uma FaultRule no <TargetEndpoint>.

FaultRules vs. a política RaiseFault

As regras de falhas e a política RaiseFault podem parecer, à primeira vista, formas alternativas de realizar o processamento de falhas. Em alguns aspetos, isso é verdade. Mas também funcionam em conjunto. Esta secção explica a relação entre os dois. Compreender esta relação deve ajudar a conceber o processamento de falhas, especialmente se quiser usar ambos.

Em resumo:

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

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

    Por exemplo, se quiser gerar um erro se o código de estado HTTP na resposta do serviço de destino for superior a 200, adicione uma política RaiseFault no fluxo de resposta. Terá um aspeto semelhante a este:

    <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 a app cliente.

O que acontece quando uma política RaiseFault aciona um erro, que coloca o proxy num estado de erro, o que executa potencialmente uma FaultRule? É aqui que as coisas podem ficar um pouco complicadas. Se a política RaiseFault devolver uma mensagem de erro e for acionada uma FaultRule e devolver uma mensagem de erro, o que é devolvido à app cliente?

  • Uma vez que a FaultRule ou a DefaultFaultRule é executada após a política RaiseFault, os dados de resposta da FaultRule têm prioridade.
  • Os dados de resposta da política RaiseFault (código de estado ou payload de mensagem) são usados se esses dados não forem definidos pela FaultRule ou pela DefaultFaultRule.
  • Se a política RaiseFault e a FaultRule adicionarem cabeçalhos HTTP personalizados, ambos são incluídos na resposta. Os nomes de cabeçalhos duplicados criam um cabeçalho com vários valores.

Segue-se um exemplo do que é definido por uma política RaiseFault e uma FaultRule, e o que é devolvido à app cliente. Os exemplos foram concebidos para serem breves e não para ilustrar as práticas recomendadas.

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

A app cliente recebe:

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

<- A política de regras de falhas define isto:

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

<- A política RaiseFault define isto:

Status Code: 468
Payload: {"DOH!":"Try again."}
Header:
  errorNote: woops

Condições de construção

As condições são fundamentais para a execução de FaultRule. Cria condições FaultRule da mesma forma que cria outras condições no Apigee, como para fluxos condicionais ou condições RaiseFault.

Para contextualizar o resto desta secção, aqui está uma regra de falha de exemplo que tem uma condição FaultRule externa e uma condição Step 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 dos 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 falha, intercete o erro numa condição através da variável fault.name. Por exemplo:

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

O nome do erro é apresentado na mensagem de erro predefinida. Por exemplo, no seguinte, o nome da falha é FailedToResolveAPIKey. Neste caso, uma variável de fluxo denominada fault.name é definida com o valor FailedToResolveAPIKey.

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

Assim, a condição teria o seguinte aspeto:

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

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

{policy_namespace}.{policy_name}.failed

A variável *.failed está disponível quando uma política falha. Seguem-se exemplos de variáveis *.failed para diferentes políticas. Para ver os espaços de nomes das políticas, consulte as variáveis de fluxo em cada tópico de referência de políticas.

Outras variáveis disponíveis

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

  • As variáveis da política que falhou.
  • As variáveis de mensagens HTTP que existem no ponto de falha. Por exemplo, se for gerado um erro na resposta, uma FaultRule no <TargetEndpoint> pode usar dados HTTP response.status.code, message.content, error.content e assim sucessivamente. Em alternativa, se uma política de quotas falhar, pode usar a variável ratelimit.{quota_policy_name}.exceed.count. Use a ferramenta de depuração e a referência de políticas para ajudar a determinar que variáveis e dados HTTP estão disponíveis.

Mais informações

Práticas recomendadas para o processamento de falhas

O processamento de falhas é uma tarefa de design arquitetónico importante para o desenvolvimento de proxies de API. É importante dedicar tempo a descobrir como e quando vai processar os erros, determinar o que as mensagens de erro vão dizer e criar formatos de mensagens de erro. Depois (ou à medida que) descobrir esses aspetos, use estas práticas recomendadas para ajudar na implementação do processamento de falhas.

Seguem-se algumas práticas recomendadas para conceber e criar o processamento de falhas:

  • Em FaultRules, pode 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 pode usar AssignMessage para definir variáveis usadas para outros fins, por exemplo, para variáveis referenciadas por políticas de registo que são executadas no PostClientFlow ou em FlowHooks. Considere também registar uma mensagem, por exemplo, com a política MessageLogging ou a política ServiceCallout, se quiser registar erros específicos em condições de falha específicas.
  • Não especifique políticas RaiseFault como passos numa FaultRule. É melhor usar políticas AssignMessage para definir ou alterar elementos de mensagens, incluindo a carga útil, os cabeçalhos ou o código de estado.
  • Para cada FaultRule ou para todas, exceto a FaultRule avaliada mais recentemente, forneça um outer <Condition> anexado como filho do elemento <FaultRule>. A condição de execução de uma FaultRule sem uma condição explícita especificada é implicitamente avaliada como true. Um elemento <Condition> anexado como filho de um elemento <Step> não é usado para determinar se a condição de execução da FaultRule é avaliada como true ou false. As condições do passo só são avaliadas depois de o Apigee executar a FaultRule que as contém. Numa FaultRule, é comum ter vários passos com políticas AssignMessage (ou outras), cada um com uma condição de passo.

  • Para processar erros em várias políticas do mesmo tipo (por exemplo, várias políticas de quota), crie uma FaultRule por erro de política que provavelmente vai receber e, em seguida, distinga entre erros separados com condições anexadas a passos. Por exemplo, crie uma FaultRule para processar um erro nas políticas de quotas, como QuotaViolation, e uma FaultRule separada para InvalidApiKey. (Consulte a referência de erros de políticas para ver os erros de políticas. À medida que descobre erros adicionais que têm de ser processados, pode voltar mais tarde e adicioná-los às suas FaultRules. Não há problema em ser iterativo, embora exija a reimplementação do proxy.) Esta abordagem permite-lhe detetar o mesmo tipo de erro, independentemente da política que o gera, o que torna o seu XML FaultRules eficiente.

    As condições do passo interno oferecem-lhe um controlo mais detalhado. Por exemplo, se estiver a aplicar a quota de programador individual e a quota global com duas políticas no fluxo de pedidos, defina a condição externa FaultRule para ser acionada no erro QuotaViolation (que é lançado quando a quota é excedida em qualquer dos casos). Em seguida, defina condições de passos para avaliar as variáveis exceed.count específicas em ambas as suas políticas de quotas. Apenas o erro relevante é enviado para o cliente (excesso de quota do programador ou excesso de quota global). Segue-se um exemplo desta 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 outro exemplo, consulte esta discussão sobre o tratamento de falhas de políticas.

  • Para processar erros quando usa uma única política de um tipo, considere uma única regra de falha que é executada quando essa política falha e inclua vários passos que são mapeados para cada erro possível. Isto simplifica o seu XML através da utilização de uma única FaultRule em vez de várias FaultRules (uma para cada tipo de erro). Por exemplo, pode especificar que diferentes passos da política AssignMessage são executados em condições diferentes, da seguinte forma:

    <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 ocorrem (do lado do cliente <ProxyEndpoint> ou do lado do destino <TargetEndpoint>). Inclua FaultRules para cada política que aparece em cada localização.
  • Quando usar políticas RaiseFault em conjunto com FaultRules, coordene os dados de resposta que são enviados de volta quando a política RaiseFault e uma FaultRule devolvem dados. Por exemplo, se tiver uma política RaiseFault que defina o código de estado HTTP, não configure também um passo AssignMessage numa FaultRule que repõe o código de estado. O pior que pode acontecer é o código de estado predefinido ser devolvido à app cliente.

  • O elemento <DefaultFaultRule> complementa o elemento <FaultRules> para lhe dar mais controlo sobre as políticas que o proxy executa quando está a processar um estado de falha. Se especificar um <DefaultFaultRule>, este é executado se uma ou ambas as seguintes condições se verificarem:

    • Nenhuma outra FaultRule foi executada. Uma exceção aqui é se não existir nenhum elemento <FaultRules> configurado.
    • Se o elemento secundário <AlwaysEnforce> de <DefaultFaultRule> for verdadeiro.

    Também pode especificar um elemento <Condition> num elemento <DefaultFaultRule>. Pode fazê-lo para excluir a sua execução com base num determinado estado do pedido ou numa mensagem de erro pendente, por exemplo, se um cabeçalho específico estiver presente ou em falta.

    Use um <DefaultFaultRule> com <AlwaysEnforce> definido como true, se tiver uma ou mais políticas que quer que o proxy execute sempre, independentemente de ter sido executada uma FaultRule anterior. Um cenário possível: suponhamos que quer injetar um cabeçalho na resposta em todos os casos, quer o pedido de proxy tenha resultado numa falha ou não, e quer a falha tenha sido processada anteriormente ou não. Em seguida, anexaria uma política AssignMessage adequada na secção <PostFlow>/<Response> e também anexaria a mesma política na secção <DefaultFaultRule> com <AlwaysEnforce> definido como true.

Padrão para processamento de falhas centralizado e reutilizável

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

Criar FaultRules

Para adicionar uma FaultRule, tem de editar a configuração XML do ProxyEndpoint ou do TargetEndpoint. Pode usar a IU do Apigee para fazer esta edição no painel Código da vista Desenvolver de um proxy de API ou editar o ficheiro XML que define o ProxyEndpoint ou o TargetEndpoint.

Se criar FaultRules na IU do Apigee, primeiro crie as políticas que quer executar e, em seguida, adicione-as à configuração FaultRule. (Recebe um erro na IU se tentar guardar uma FaultRule que faça referência a uma política que ainda não foi criada.)

Adicionar políticas a uma FaultRule

Embora possa colocar qualquer política na FaultRule, usa frequentemente a política AssignMessage para gerar uma mensagem de resposta personalizada para uma condição de erro. A política AssignMessage permite-lhe configurar uma resposta HTTP com carga útil, código de estado HTTP e cabeçalhos.

O exemplo abaixo mostra uma configuração típica da política AssignMessage:

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

Repare que não especifica um elemento <AssignTo>. Isto significa que será atribuído à mensagem ambiente, consoante o local onde a política está anexada.

Já pode usar esta política na sua FaultRule. Repare como faz referência à política AssignMessage pelo 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 implementa a configuração acima, o proxy de API executa a política AssignMessage denominada AM-Invalid-Key sempre que uma app apresenta uma chave de API inválida.

Pode executar várias políticas numa FaultRule, como mostra o exemplo seguinte:

<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 pela ordem definida. Por exemplo, pode usar a política MessageLogging, a política ExtractVariables, a política AssignMessage ou qualquer outra política na FaultRule. Tenha em atenção que o processamento da FaultRule é interrompido imediatamente se ocorrer uma das seguintes situações:

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

Definir a mensagem de erro personalizada devolvida de uma FaultRule

Como prática recomendada, deve definir respostas de erro claras das suas APIs. Deste modo, fornece informações consistentes e úteis aos seus clientes.

O exemplo da política AssignMessage seguinte usa as etiquetas <Payload> e <StatusCode> para definir a resposta de erro personalizada enviada de volta para o cliente num 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>

Esta resposta inclui:

  • A carga útil que contém a mensagem de erro e um endereço de email para contactar o apoio técnico.
  • O código de estado HTTP devolvido na resposta.

Criar uma DefaultFaultRule

Uma DefaultFaultRule funciona como um controlador de exceções para qualquer erro que não seja processado explicitamente por outra FaultRule. Se as condições de todas as FaultRules não corresponderem ao erro, a DefaultFaultRule processa o erro. Ative o processamento de falhas predefinido adicionando a etiqueta <DefaultFaultRule> como um elemento secundário de um ProxyEndpoint ou um TargetEndpoint.

Por exemplo, a configuração TargetEndpoint abaixo define uma DefaultFaultRule que invoca uma política denominada 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>

A DefaultFaultRule é normalmente usada para devolver uma mensagem de erro genérica para qualquer erro inesperado, como uma mensagem que contenha informações de contacto para o apoio técnico. Esta resposta predefinida tem o duplo objetivo de fornecer informações fáceis de usar para os programadores e, ao mesmo tempo, ocultar URLs de back-end ou outras informações que possam ser usadas para comprometer o sistema.

Por exemplo, define a seguinte política AssignMessage para devolver 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 etiqueta <DefaultFaultRule> para executar a DefaultFaultRule para cada erro, mesmo que outra FaultRule já tenha sido executada. A DefaultFaultRule é sempre a última FaultRule a ser executada:

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

Uma utilização da DefaultFaultRule é determinar o tipo de erro que ocorre quando não é possível determiná-lo de outra forma. Por exemplo, se o proxy de API estiver a falhar devido a um erro que não consegue determinar, pode usar a DefaultFaultRule para invocar a seguinte política AssignMessage. Esta política escreve o valor fault.name num cabeçalho denominado 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>

Em seguida, pode ver o cabeçalho na ferramenta de depuração ou na resposta para ver o que causou o erro.

Adicionar registo de mensagens ao PostClientFlow

O PostClientFlow é o único fluxo que é executado depois de o proxy entrar no estado de erro. Apenas a política MessageLogging pode ser anexada a este fluxo, que é executado depois de a resposta ser enviada de volta ao cliente. Embora anexar a política MessageLogging a este fluxo não seja, tecnicamente, um processamento de erros, pode usá-la para registar informações em caso de erro. Uma vez que é executada independentemente de o proxy ter sido bem-sucedido ou não, pode colocar políticas de registo de mensagens no PostClientFlow e ter a garantia de que são sempre executadas.

Processamento de falhas de políticas no fluxo atual

Os exemplos apresentados até agora usam uma FaultRule no ProxyEndpoint ou no TargetEndpoint para processar quaisquer erros de política como parte do estado de erro. Isto deve-se ao facto de o valor predefinido do elemento continueOnError de uma política ser false, o que significa que, quando ocorre um erro numa política, o controlo é direcionado para o estado de erro. Quando se encontra no estado de erro, não pode devolver o controlo ao pipeline normal e, normalmente, devolve alguma forma de mensagem de erro à app de chamada.

No entanto, se definir o elemento continueOnError como true para uma política, o controlo permanece no fluxo atual e a política seguinte no pipeline é executada após a política que causou o erro. A vantagem de processar o erro no fluxo atual é que pode ter uma forma de recuperar do erro para concluir o processamento do pedido.

Abaixo, é apresentada uma política VerifyAPIKey denominada 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 da API estiver em falta ou for inválida, a política VerifyAPIKey define a variável oauthV2.verify-api-key.failed como true, mas o processamento continua no fluxo atual.

Em seguida, adicione a política VerifyAPIKey como um passo 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>

Repare como o passo seguinte no PreFlow usa uma condição para testar a existência de um erro. Se ocorrer um erro na política VerifyAPIKey, a política denominada FaultInFlow é executada. Caso contrário, a política FaultInFlow é ignorada. A política FaultInFlow pode fazer muitas coisas, como registar o erro, tentar corrigir o erro ou realizar alguma outra ação.

Acionar um erro através da política RaiseFault

Pode usar a política RaiseFault em qualquer altura num fluxo para acionar um erro. Quando uma política RaiseFault é executada, termina o fluxo atual e transfere o controlo para o estado de erro.

Uma utilização da política RaiseFault é testar uma condição específica que outra política pode não detetar. No exemplo acima, adicionou uma etiqueta <Condition> a uma etiqueta <Step> PreFlow que fez com que a política FaultInFlow fosse executada se a condição for cumprida. Se FaultInFlow for uma política RaiseFault, o controlo é transferido para o estado de erro. Em alternativa, pode inserir uma política RaiseFault num fluxo para depurar e testar as suas FaultRules.

Quando uma política RaiseFault aciona um erro, pode usar a FaultRule e a condição seguintes para o processar:

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

Tenha em atenção que a condição testa uma falha denominada RaiseFault. A política RaiseFault define sempre o valor de fault.name como RaiseFault. Também pode definir variáveis personalizadas numa política RaiseFault. Se o fizer, pode testar essas variáveis nos elementos de condição.

Processamento personalizado de códigos de erro HTTP do servidor de destino

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

Por predefinição, o Apigee trata os códigos de resposta HTTP no intervalo 1xx-3xx como êxito e os códigos de resposta HTTP no intervalo 4xx-5xx como falha. Isto 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, em seguida, devolve uma mensagem de erro diretamente ao cliente que está a fazer o pedido.

Pode criar controladores personalizados para quaisquer códigos de resposta HTTP. Por exemplo, pode não querer tratar todos os códigos de resposta HTTP no intervalo 4xx-5xx como "falha", mas apenas 5xx, ou pode querer devolver mensagens de erro personalizadas para os códigos de resposta HTTP 400 e 500.

No exemplo seguinte, usa a propriedade success.codes para configurar o TargetEndpoint para tratar os códigos de resposta HTTP 400 e 500 como um êxito, juntamente com os códigos HTTP predefinidos. Ao tratar esses códigos como um êxito, o TargetEndpoint assume o processamento da mensagem de resposta, em vez de invocar o estado de 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 pode ver neste exemplo, pode usar carateres universais para definir a propriedade success.codes para um intervalo de valores.

A definição da propriedade success.codes substitui os valores predefinidos. Por conseguinte, se quiser adicionar o código HTTP 400 à lista de códigos de êxito predefinidos, defina esta propriedade como:

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

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

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

Agora, pode definir processadores personalizados para os códigos de resposta HTTP 400 e 500 para devolver uma mensagem de resposta personalizada à app que está a fazer o pedido. O TargetEndpoint seguinte usa a política denominada ReturnError para processar 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>

Esta configuração TargetEndpoint faz com que a política denominada ReturnError processe a resposta sempre que o TargetEndpoint encontrar um código de resposta HTTP de 400 OU 500.

Taxonomia de falhas

Os serviços de API organizam as falhas nas seguintes categorias e subcategorias.

Categoria Subcategoria Nome da falha Descrição
Mensagens Falhas que ocorrem durante o fluxo de mensagens (não incluindo falhas de políticas)
Falhas personalizadas {fault_name} Quaisquer falhas processadas explicitamente pelo proxy de API através da política RaiseFault
Códigos de resposta InternalServerError, NotFound Códigos de erro HTTP 5xx, 4xx
Falhas de encaminhamento NoRoutesMatched Falha ao selecionar um TargetEndpoint com nome para um pedido
Falhas de classificação NotFound Falhas causadas por um URI de pedido que não corresponde a nenhum BasePath para nenhuma configuração de ProxyEndpoint (ou seja, nenhum proxy de API corresponde ao URL no pedido da app cliente)
Transportes Erros ao nível do transporte HTTP
Conetividade ConnectionRefused, ConnectionReset, ConnectionTimeout As falhas ocorrem ao estabelecer ligações de rede ou ao nível do transporte
Pedir validações ContentLengthMissing, HostHeaderMissing Ocorrem falhas durante as verificações semânticas em cada pedido
Validações de respostas Ocorrem falhas durante as verificações semânticas em todas as respostas
Erros de IO SSLHandshakeError, ReadTimeout, ReadError, WriteTimeout, WriteError, ChunkError Erros de leitura/escrita nos pontos finais do cliente ou de destino, limites de tempo, erros de TLS/SSL e erros fragmentados
Sistema Erros de tempo de execução não definidos
Memória OutOfMemory, GCOverLimit Falhas relacionadas com a memória
Discussão RogueTaskTerminated Falhas, como a terminação de tarefas descontroladas
Política As falhas para cada tipo de política estão definidas na referência de políticas.

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

  • Motivo
  • Atributos personalizados definidos pelo utilizador