Maneja las fallas

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Pueden surgir muchas condiciones de error mientras los proxies de API entregan solicitudes desde aplicaciones. Por ejemplo, los proxies de API pueden encontrar problemas de red cuando se comunican con servicios de backend, las apps pueden presentar credenciales vencidas, mensajes de solicitud pueden tener un formato incorrecto, etcétera.

Cuando se genera un error después de que una app cliente llama a un proxy de API, se muestra un mensaje de error al cliente. De forma predeterminada, el cliente recibe un mensaje de error críptico sin detalles ni orientación. Pero si quieres reemplazar los mensajes de error predeterminados por mensajes personalizados más útiles y, además, enriquecerlos con elementos como los encabezados HTTP adicionales, debes configurar el manejo de errores personalizado en Apigee.

El control de errores personalizados también te permite agregar funciones como el registro de mensajes cada vez que se produce un error.

Antes de hablar sobre la implementación del control de errores personalizados en los proxies de la API, es útil comprender cómo se producen los errores y cómo reaccionan los proxies de la API.

Videos

Mira los siguientes videos para obtener más información sobre el control de fallas.

Video Descripción
Introducción al control de fallas y flujo de errores Obtén información sobre el control de fallas y lo que sucede cuando se genera un error en un proxy de API.
Controla fallas con reglas de fallas Obtén información sobre cómo controlar las fallas mediante las reglas de fallas.
Genera fallas personalizadas mediante la política RaiseFault Genera fallas personalizadas durante el entorno de ejecución de la API mediante la política RaiseFault.
Define reglas de falla en el proxy de API y los extremos de destino Define las reglas de fallas en el proxy de API y los extremos de destino, y comprende las diferencias.
Comprende el orden de ejecución de las reglas de fallas Comprende el orden de ejecución de las reglas de falla en el proxy de API y los extremos de destino.
Define una regla de falla predeterminada Define la regla de falla predeterminada para controlar errores genéricos en tu API.

Cómo se producen los errores

En primer lugar, solo abordaremos cómo se producen errores. Conocer cómo se producen los errores te ayudará a planificar las diferentes situaciones en las que deseas implementar un control de errores personalizado.

Errores automáticos

Un proxy de API muestra un error de forma automática en las siguientes situaciones:

  • Una política muestra un error. Por ejemplo, si una llamada a la API envía una clave vencida, la política VerifyAPIKey muestra de forma automática un error. Si el número de llamadas a la API supera un límite determinado, se muestra un error en la Política de Cuotas o la Política de SpikeArrest. (Consulta la referencia de errores de la política para ver los tipos de errores que pueden generarse).
  • Existe un problema en el flujo de mensajes del proxy de la API, como un error de enrutamiento.
  • Hay una falla de backend, como un error de HTTP debido a fallas en el protocolo, errores de TLS/SSL o un servicio de destino no disponible.
  • Existe una falla a nivel del sistema, como una excepción de memoria insuficiente.

Para obtener más información sobre estos errores, consulta taxonomía de fallas en este tema.

Errores personalizados

Para situaciones en las que no se produzca un error automático, es posible que aparezca un error personalizado. Por ejemplo, si una respuesta contiene la palabra unavailable o si el código de estado HTTP es mayor que 201. Para ello, agrega una política RaiseFault en el lugar apropiado de un flujo de proxy de API.

Puedes agregar una política RaiseFault a un flujo de proxy de API de la misma manera en que lo haces con cualquier otra política. En el siguiente ejemplo de configuración del proxy, la política Raise-Fault-1 se adjunta a la respuesta TargetEndpoint. Si la palabra unavailable está presente en la respuesta del servicio de destino, se ejecuta la política de RaiseFault y genera un error.

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

Esto es solo para demostrar que puedes generar errores personalizados. Encontrarás más detalles sobre la política RaiseFault en la sección política RaiseFault en comparación con la política RaiseFault.

Para ver más ejemplos, consulta estas publicaciones de la Comunidad de Apigee:

¿Qué hacen los proxies de API cuando se generan errores?

Esto es lo que sucede cuando un proxy muestra un error

Sal de la canalización del proxy.

Cuando un proxy de API encuentra un error, sin importar de cómo ocurra, sale de la canalización de flujo normal, ingresa un estado de error y muestra un mensaje de error a la app cliente. Una vez que el proxy de API ingresa al estado de error, no puede volver a procesar la canalización de flujo normal.

Por ejemplo, supongamos que un proxy de API tiene políticas en el siguiente orden en la solicitud de ProxyEndpoint:

  1. Verifica la clave de API
  2. Cuota
  3. JSON a XML

Si se produce un error durante la verificación de la clave de API, el proxy de API pasa al estado de error. Las políticas de Cuotas y JSON a XML no se ejecutan, el proxy no continúa con TargetEndpoint y se muestra un mensaje de error a la aplicación cliente.

Comprueba la política FaultRules

En el estado de error, los proxies de API también comprueban la presencia de lo siguiente (en orden) en la configuración del proxy de API antes de mostrar un mensaje de error predeterminado a la app cliente:

  1. Una sección <FaultRules>, que contiene la lógica para activar mensajes de error personalizados (y otras políticas) basadas en las condiciones específicas que definas.
  2. Una sección <DefaultFaultRule>, que activa un mensaje de error predeterminado en las siguientes situaciones:
    • No se definió ninguna <FaultRules>.
    • No se ejecuta ninguna <FaultRules> existente.
    • El elemento <AlwaysEnforce> se establece como verdadero.

En esencia, el proxy de API te brinda la oportunidad de mostrar un mensaje de error personalizado y activar otra lógica. Si el proxy no encuentra ninguna de esas secciones o si existen, pero no se activó un error personalizado, el proxy envía su propio mensaje predeterminado que Apigee genera.

Ejemplo del control de fallas simples

Comencemos con un ejemplo simple, en el que una llamada a un proxy de API no contiene una clave de API obligatoria. De forma predeterminada, esta es la respuesta que se muestra a la 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"}}}

Los usuarios de la API pueden descubrir el mensaje de error, pero es posible que no. Y muchos errores predeterminados son más sutiles y más difíciles de descifrar.

Como desarrollador de API, depende de ti cambiar este mensaje para satisfacer las necesidades de la persona que recibirá el mensaje de error, ya sea un desarrollador de apps para iOS o un grupo de pruebas internas que tenga sus propio requisitos de formato de mensajes de error. .

A continuación, se muestra un ejemplo básico de cómo crearías un mensaje de error personalizado para controlar este error. Para esto, 1) se requiere una política que defina el mensaje personalizado, y 2) una FaultRule que ejecute la política cuando el proxy pase a un estado de error.

1. Crea una política que defina el mensaje personalizado

Primero, crea una política que defina el mensaje de error personalizado. Puedes usar cualquier tipo de política, como una política de AssignMessage, que pueda establecer una carga útil y encabezados HTTP opcionales, como el código de estado y la frase de motivo. Para esto, la política de AssignMessage es ideal. Te permite controlar la carga útil de mensajes, establecer un código de estado HTTP diferente, establecer una frase de motivo HTTP diferente y agregar encabezados HTTP.

No es necesario adjuntar la política a un flujo; solo debes crearla, como se describe en Crea la política.

A continuación, se muestra un ejemplo de la política AssignMessage:

  • Muestra un mensaje JSON.
  • Establece un código de estado HTTP (911, que es un código de estado obvio que no existe simplemente para ilustrar la flexibilidad que tienes). El código de estado aparece en el encabezado HTTP.
  • Establece una frase de motivo HTTP (para reemplazar la frase de motivo Unauthorized predeterminada para este error de clave de API faltante). La frase de motivo aparecerá junto al código de estado en el encabezado HTTP.
  • Crea y propaga un nuevo encabezado HTTP llamado 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>

Cuando se ejecuta esta política, la respuesta a la app cliente será similar a la siguiente: Compárala con la respuesta predeterminada que se mostró antes.

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."}

Sí, no tiene mucho sentido, pero te muestra lo que es posible. Al menos ahora, el desarrollador que recibe el mensaje sabe que olvidó incluir una clave de API como parámetros de búsqueda.

Pero ¿cómo se ejecuta esta política? En la siguiente sección, se muestra.

2. Crea la <FaultRule> para activar la política.

En las secciones <ProxyEndpoint> o <TargetEndpoint> de la configuración del proxy, agregarás un bloque XML <FaultRules> que contenga una o más secciones <FaultRule> individuales. Cada FaultRule representa un error diferente que deseas controlar. En este ejemplo sencillo, usaremos solo una FaultRule para mostrarte qué está compuesto.

También debes agregar un <DefaultFaultRule> para proporcionar un mensaje de error general personalizado si no se ejecuta ninguna de las FaultRules.

Ejemplo

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

Puntos clave:

  • Las FaultRules se definen en el ProxyEndpoint. Esto es importante. Más información sobre cómo colocar FaultRules en ProxyEndpoint en comparación con TargetEndpoint más adelante.
  • <Name>: Es el nombre de la política que se ejecutará. El nombre proviene del atributo name de la política en el elemento superior, como se muestra en el ejemplo de la política anterior.

  • <Condition>: Apigee evalúa la condición y ejecuta la política solo si la condición es verdadera. Si hay varias FaultRules que se evalúan como verdaderas, Apigee ejecuta la primera que sea verdadera. (Importante: El orden en el que se evalúan las FaultRules, de forma descendente o ascendente, se diferencia del de TargetEndpoint y el ProxyEndpoint, como se describe en la sección Varias lógicas de FaultRules y de ejecución). Si no incluyes una condición, FaultRule será verdadera de manera automática. Pero no es una práctica recomendada. Cada FaultRule debe tener su propia condición.

  • <DefaultFaultRule>: Si no se ejecuta una FaultRule personalizada, se ejecuta <DefaultFaultRule> y envía un mensaje personalizado más genérico en lugar del mensaje predeterminado críptico generado por Apigee. Un <DefaultFaultRule> también puede tener una <Condition>, pero en la mayoría de los casos, no incluirás uno, porque quieres que se ejecute sin importar qué sea el último recurso.

    Por lo general, DefaultFaultRule se usa a fin de mostrar un mensaje de error genérico para cualquier error inesperado. Un ejemplo sería un mensaje que contiene la información de contacto para recibir asistencia técnica. Esta respuesta predeterminada tiene el doble propósito de proporcionar información intuitiva para el desarrollador y, al mismo tiempo, ofuscar las URL de backend o alguna otra información que pueda usarse a fin de comprometer el sistema.

Varias lógicas de FaultRules de ejecución

En la sección Ejemplo de control de fallas simples, usamos un ejemplo sencillo de una sola FaultRule y una condición. En un proyecto de API real, con todos los errores posibles que se pueden generar, es probable que tengas varias FaultRules y una DefaultFaultRule en <ProxyEndpoint> y <TargetEndpoint>. En última instancia, sin embargo, solo se ejecuta una FaultRule cuando un proxy de API entra en un estado de error.

En esta sección, se describe la lógica que Apigee usa para controlar las FaultRule, desde cómo llega a una sola FaultRule para ejecutarse hasta cómo se manejan las condiciones del paso interno cuando se activa su falla. En esta sección, también se proporciona orientación sobre cuándo definir FaultRules en las <ProxyEndpoint> frente a <TargetEndpoint>, y se describe la relación entre FaultRules y la Política de RaiseFault.

Ejecución de FaultRules

En resumen, esta es la lógica que Apigee usa cuando el proxy de la API entra en un estado de error. Ten en cuenta que hay una leve diferencia entre la evaluación de FaultRules en ProxyEndpoint en comparación con TargetEndpoint.

  1. Apigee evalúa las FaultRules en ProxyEndpoint o TargetEndpoint, según dónde se generó el error:
    • ProxyEndpoint: Apigee comienza con la <FaultRule> final en el archivo XML de configuración y sube para evaluar la<Condition> de cada <FaultRule> (la condición exterior, no las condiciones internas de <Step>).
    • TargetEndpoint: Apigee comienza con la <FaultRule> superior en el archivo de configuración y baja para evaluar la <Condition> de cada <FaultRule> (la condición externa, no las condiciones internas de <Step>).
  2. Ejecuta la primera FaultRule cuya condición es verdadera. Si una FaultRule no tiene condición, es verdadera de forma predeterminada.
    • Cuando se ejecuta una FaultRule, todos los pasos dentro de FaultRule se evalúan en orden, desde arriba hacia abajo en la configuración de XML. Los Steps sin condiciones se ejecutan de forma automática (las políticas se ejecutan) y los Steps que tienen una <Condition> que se evalúa se ejecución (las condiciones que se evalúan como code no se ejecutan).

    • Si se ejecuta una FaultRule, pero no se ejecutan pasos en la FaultRule (porque sus condiciones se evalúan como code“falsa”), el mensaje de error predeterminado generado por Apigee se muestra a la app cliente. La <DefaultFaultRule> no se ejecuta, porque Apigee ya ejecutó su única FaultRule.

  3. Si no se ejecuta FaultRule, Apigee ejecuta el <DefaultFaultRule>, si está presente.

A continuación, se muestran ejemplos con comentarios intercalados.

Ejecución de ProxyEndpoint

La evaluación de FaultRules de ProxyEndpoint es desde abajo hacia arriba, así que comienza a leer en la última FaultRule del siguiente ejemplo y continúa hacia arriba. Observa la última DefaultFaultRule.

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

Ejecución de TargetEndpoint

La evaluación de FaultRules de TargetEndpoint es desde abajo hacia arriba, por lo tanto, comienza a leer en la primera FaultRule en la siguiente muestra y continúa hacia abajo. Observa la última DefaultFaultRule.

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

Orden de las reglas de falla

Como puedes ver en el ejemplo anterior, el orden en el que se colocan las FaultRules es importante en función de si el error se genera en el ProxyEndpoint en comparación con TargetEndpoint.

Por ejemplo:

Orden de ProxyEndpoint Orden de TargetEndpoint

En el siguiente ejemplo, dado que la evaluación es de abajo arriba, la FaultRule 3 se ejecuta, lo que significa que no se evalúan las FaultRules 2 y 1.

5. FaultRule 1: FALSO

4. FaultRule 2: VERDADERO

3. FaultRule 3: VERDADERO

2. FaultRule 4: FALSO

1. FaultRule 5: FALSO

En el siguiente ejemplo, dado que la evaluación es de arriba abajo, FaultRule 2 se ejecuta, lo que significa que no se evalúan las FaultRules 3, 4 y 5.

1. FaultRule 1: FALSO

2. FaultRule 2: VERDADERO

3. FaultRule 3: VERDADERO

4. FaultRule 4: FALSO

5. FaultRule 5: FALSO

Políticas que se deben incluir

Puedes ejecutar cualquier política desde una FaultRule si las colocas en Pasos. Por ejemplo, puedes ejecutar una política AssignMessage para dar formato a una respuesta a la app cliente y, luego, registrar un mensaje con la política MessageLogging. Las políticas se ejecutan en el orden en que las colocas (desde arriba hacia abajo en el XML).

Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre continueOnError).

Puede parecer que el encabezado se repite, pero hay un matiz en particular con respecto a un error de proxy que hace que un proxy de API entre en un estado de error o, mejor dicho, no ingrese un estado de error: el atributo continueOnError en una política.

En resumen: Un proxy de API evalúa <FaultRules> y <DefaultFaultRule> solo si el proxy ingresó en un estado de error. Eso significa que, incluso si una condición FaultRule se evalúa como verdadera, no se activará si el proxy no tiene un estado de error.

Sin embargo, este es el ejemplo de un error que ocurre y el proxy no ingresa un estado de error. En cualquier política, puedes configurar un atributo en el elemento superior llamado continueOnError. Ese atributo es muy importante con respecto al control de errores, ya que determina si el proxy ingresa en un estado de error si la política falla. En la mayoría de los casos, querrás mantener el continueOnError="false" predeterminado, que pone el proxy en estado de error si falla la política y se activa el manejo de errores personalizados. Sin embargo, si continueOnError="true" (por ejemplo, si no quieres que una llamada de servicio detenga la ejecución del proxy), el proxy no entrará en un estado de error si la política falla, y el proxy no analizará tus FaultRules.

Para obtener información sobre los errores de registro cuando continueOnError="true", consulta Controla fallas de política dentro del flujo actual.

Dónde definir FaultRules: ProxyEndpoint o TargetEndpoint

Cuando un proxy de API experimenta un error, este se genera en <ProxyEndpoint> (solicitud o respuesta desde la app cliente) o en <TargetEndpoint> (solicitud o respuesta desde el servicio de destino). Donde sea que ocurra el error es cuando Apigee busca FaultRules.

Por ejemplo, si un servidor de destino no está disponible (código de estado HTTP 503), el proxy de API tendrá un estado de error en la respuesta <TargetEndpoint> y el flujo del proxy de API normal no continuaría a <ProxyEndpoint>. Si tienes FaultRules definidas solo en el <ProxyEndpoint>, no controlarán ese error.

Les doy otro ejemplo. Si una política RaiseFault en la respuesta <ProxyEndpoint> activa un error, no se ejecutará una FaultRule en <TargetEndpoint>.

FaultRules en comparación con la política RaiseFault

Las reglas con fallas y la política RaiseFault pueden parecer formas alternativas de lograr el control de errores y de alguna manera es verdadero. Pero también funcionan en conjunto. En esta sección, se explica la relación entre las dos. Comprender esta relación te ayudará a diseñar el control de los errores, en especial si deseas usar ambos.

En resumen:

  • Las reglas de fallas siempre se evalúan cuando un proxy de API entra en un estado de error.

  • La política RaiseFault es una forma de colocar un proxy de API en un estado de error cuando no se hubiera generado un error.

    Por ejemplo, si deseas generar un error si el código de estado HTTP en la respuesta del servicio de destino es superior a 200, agrega una política de RaiseFaul en tu flujo de respuesta. Se vería algo así:

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

    La política RaiseFault también envía un mensaje de error a la app cliente.

¿Qué sucede cuando una política RaiseFault activa un error, que pone el proxy en un estado de error, lo que podría ejecutar una FaultRule? En estos casos, las cosas se pueden complicar un poco. Si la política de RaiseFault muestra un mensaje de error y se activa una FaultRule que muestra un mensaje de error, ¿qué se muestra a la app cliente?

  • Dado que FaultRule o DefaultFaultRule se ejecuta después de la política RaiseFault, los datos de respuesta de FaultRule obtienen los datos.
  • Los datos de respuesta de la política de RaiseFault (código de estado, frase de motivo o carga útil de un mensaje) se usan si esos datos no están configurados por FaultRule o DefaultFaultRule.
  • Si la política de RaiseFault y FaultRule agregan encabezados HTTP personalizados, se incluyen ambos en la respuesta. Los nombres de encabezado duplicados crean un encabezado con varios valores.

Este es un ejemplo de lo que establece una política RaiseFault y una FaultRule y lo que se muestra en la app cliente. Las muestras se diseñan con el fin de abreviar, no para las prácticas recomendadas.

Lo que se configura mediante una política de RaiseFault y una falla.

La app cliente recibe lo siguiente:

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

<- La política FaultRule establece lo siguiente:

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

<- La política RaiseFault establece lo siguiente:

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

Compila condiciones

Las condiciones son la clave para la ejecución de FaultRule. Las condiciones de FaultRule se crean de la misma manera que para otras condiciones en Apigee, como los flujos condicionales o las condiciones de RaiseFault.

Para poner el resto de esta sección en contexto, esta es una regla de falla de muestra que tiene una condición de FaultRule externa y una condición de paso 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>

Variables específicas para errores de la política

Las variables fault.name y {policy_namespace}.{policy_name}.failed están disponibles cuando una política genera un error.

fault.name

Cuando una política falla, detecta el error en una condición mediante la variable fault.name. Por ejemplo:

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

El nombre del error aparece en el mensaje de error predeterminado. Por ejemplo, en el siguiente ejemplo, el nombre del error es FailedToResolveAPIKey. En este caso, una variable de flujo llamada fault.name se establece en el valor FailedToResolveAPIKey.

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

La condición se vería de la siguiente manera:

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

Consulta la referencia de errores de la política para ver una lista de errores relacionados con las políticas.

{policy_namespace}.{policy_name}.failed

La variable *.failed está disponible cuando falla una política. A continuación, se muestran ejemplos de variables *.failed para diferentes políticas. Para los espacios de nombres de políticas, consulta las variables de flujo en cada tema de referencia de la política.

Otras variables disponibles

Cuando un proxy de API entra en estado de error, las únicas variables disponibles para usar en las condiciones son las siguientes:

  • Las variables de la política que fallaron.
  • Las variables de mensajes HTTP que existen en el punto de falla. Por ejemplo, si se genera un error en la respuesta, una FaultRule en <TargetEndpoint> podría usar datos HTTP response.status.code, message.content, error.content, etcétera. O bien, si falla una Política de cuotas, puedes usar la variable ratelimit.{quota_policy_name}.exceed.count. Usa la herramienta de depuración y la referencia de política para descubrir qué variables y datos HTTP están disponibles.

Más información

Prácticas recomendadas para el manejo de errores

El manejo de fallas es una tarea de diseño arquitectónico importante para el desarrollo del proxy de API. Es importante que te tomes tiempo para decidir cómo y cuándo controlarás los errores, determinar qué dirán los mensajes de error y diseñarás los formatos de mensajes de error. Después de averiguarlo (o mientras lo haces), usa estas prácticas recomendadas para ayudarte con la implementación del manejo de fallas.

Estas son algunas prácticas recomendadas para diseñar y compilar el control de fallas:

  • En FaultRules, puedes especificar cualquier tipo de política. El patrón más común es usar la política AssignMessage para establecer elementos específicos en la respuesta de error pendiente. También puedes usar AssignMessage para establecer variables que se usan para otros fines, por ejemplo, para las variables a las que hacen referencia las políticas de registro que se ejecutan en PostClientFlow o en FlowHooks. Además, considera registrar un mensaje, por ejemplo, con la política MessageLogging o la política ServiceCallout, si deseas registrar errores específicos en condiciones de falla específicas.
  • No especifiques las políticas RaiseFault como pasos dentro de una FaultRule. Es mejor usar políticas AssignMessage para establecer o alterar elementos de mensajes, incluidos la carga útil, los encabezados o el código de estado.
  • Para cada FaultRule, o para todos excepto el último FaultRule evaluado, proporciona una <Condition> externa adjunta como elemento secundario del elemento <FaultRule>. La condición de ejecución de una FaultRule sin una condición explícita especificada se evaluará de forma implícita como true. No se usa un elemento <Condition> adjunto como secundario de un elemento <Step> para determinar si la condición de ejecución de FaultRule se evalúa como true o false. Las condiciones del paso se evalúan solo después de que Apigee ejecuta la FaultRule que las contiene. En una FaultRule, es común tener varios Steps con políticas de AssignMessage (o cualquier otra), cada una con una condición de Step.

  • Para controlar errores en varias políticas del mismo tipo (por ejemplo, varias políticas de cuotas), crea una FaultRule por error de política que es probable que recibas y, luego, distingue entre errores separados con condiciones adjuntas a los pasos. Por ejemplo, crea una FaultRule para controlar un error en las políticas de cuota, como QuotaViolation, y una FaultRule independiente para InvalidApiKey. (Consulta la referencia de errores de la política para obtener más información. A medida que descubres errores adicionales que se deben controlar, puedes volver más adelante y agregarlos a las FaultRules. Está bien ser iterativo, aunque requiera que se vuelva a implementar el proxy). Este enfoque te permite detectar el mismo tipo de error sin importar qué política la genere, lo que hace que el XML de FaultRules sea eficiente.

    Las condiciones del paso interno te brindan un control más detallado. Por ejemplo, si aplicas una cuota individual de desarrollador y una cuota global con dos políticas en el flujo de solicitudes, configura la condición externa de FaultRule para activar en el error QuotaViolation (que se arroja cuando se supera la cuota en cualquier caso). Luego, configura las condiciones de Step para evaluar las variables de exceed.count específicas en ambas políticas de cuota. Solo se envía el error relevante para el cliente (exceso de cuotas de desarrollador o de cuota global). A continuación, se muestra un ejemplo de esta configuración:

    <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 otro ejemplo, consulta este análisis sobre el manejo de fallas de políticas.

  • Para controlar errores cuando usas una política única de un tipo, considera una sola regla de falla que se ejecute cuando esa política falle y, luego, incluye varios pasos que se asignen a cada error posible. Esto hace que tu XML sean más simples mediante una única FaultRule en vez de múltiples reglas con errores (una para cada tipo de error). Por ejemplo, puedes especificar que diferentes pasos de la política AssignMessage se ejecuten en diferentes condiciones, como por ejemplo:

    <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>
  • Agrega FaultRules en las que se producirán errores (del cliente <ProxyEndpoint> o <TargetEndpoint>). Incluye FaultRules para cada política que aparece en cada ubicación.
  • Cuando uses las políticas RaiseFault junto con FaultRules, coordina los datos de respuesta que se envían cuando se muestra la política RaiseFault y una FaultRule. Por ejemplo, si tienes una política RaiseFault que configura el código de estado HTTP, no configures también un paso de AssignMessage dentro de una FaultRule que restablece el código de estado. Lo peor que puede suceder es que el código de estado predeterminado se muestre a la app cliente.

  • El elemento <DefaultFaultRule> complementa el elemento <FaultRules> para brindarte más control sobre las políticas que ejecuta el proxy cuando controla un estado de falla. Si especificas un <DefaultFaultRule>, se ejecutará si se cumple una de las siguientes condiciones o ambas:

    • No se ejecutó ninguna otra FaultRule. Un caso especial aquí es si no hay ningún elemento <FaultRules> configurado.
    • Si el elemento secundario <AlwaysEnforce> de <DefaultFaultRule> es verdadero.

    También puedes especificar un elemento <Condition> en un <DefaultFaultRule>. Es posible que quieras hacer esto para excluir su ejecución en función del estado de la solicitud o el mensaje de error pendiente, por ejemplo, si hay un encabezado específico o no está presente.

    Usa una <DefaultFaultRule> con <AlwaysEnforce> establecido en true, si tienes una o más políticas que deseas que siempre realice el proxy, sin importar si una FaultRule anterior se ejecutó. Una situación posible: supongamos que deseas inyectar un encabezado en la respuesta en todos los casos, si la solicitud de proxy generó o no una falla y si la falla se manejó antes o no. Luego, debes adjuntar una política de AssignMessage adecuada en la sección <PostFlow>/<Response> y, también, adjuntar la misma política en <DefaultFaultRule> con <AlwaysEnforce> para configurar true.

Patrón para el control de fallas centralizado y reutilizable

Un patrón de manejo de errores para proxies de Apigee describe un patrón para el manejo de fallas centralizado sin duplicación de código.

Crea FaultRules

Para agregar una FaultRule, debes editar la configuración XML del ProxyEndpoint o TargetEndpoint. Puedes usar la UI de Apigee a fin de realizar esta edición en el panel Code de la vista Develop para un proxy de API o editar el archivo en formato XML que define ProxyEndpoint o TargetEndpoint.

Si creas FaultRules en la IU de Apigee, primero crea las políticas que deseas ejecutar y, luego, agrégalas a la configuración de FaultRule. (Obtendrás un error en la IU si intentas guardar una FaultRule que haga referencia a una política que aún no se creó).

Agrega políticas a una FaultRule

Si bien puedes establecer cualquier política en FaultRule, por lo general, puedes usar la política AssignMessage a fin de generar un mensaje de respuesta personalizado para una condición de error. AssignMessage te permite configurar una respuesta HTTP con carga útil, un código de estado HTTP, encabezados y elementos de frases de motivos.

En el ejemplo que aparece a continuación, se muestra una configuración típica de la 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>

Ten en cuenta que no especifica un elemento <AssignTo>. Esto significa que se asignará al mensaje ambiente, según dónde se adjunte la política.

Ahora puedes usar esta política en tu FaultRule. Observa cómo se hace referencia a la política AssignMessage por nombre en la 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>

Cuando implementes la configuración anterior, el proxy de API ejecutará la política AssignMessage llamada AM-Invalid-Key cada vez que una app presente una clave de API no válida.

Puedes ejecutar varias políticas en una FaultRule, como se muestra en el siguiente ejemplo:

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

Las políticas se ejecutan en el orden definido. Por ejemplo, puedes usar la política MessageLogging, la política ExtractVariables, la política de AssignMessage o cualquier otra política en FaultRule. Ten en cuenta que el procesamiento de FaultRule se detiene de inmediato si se producen alguna de estas situaciones:

  • Cualquier política en FaultRule genera un error
  • Cualquiera de las políticas en FaultRule es del tipo RaiseFault

Define el mensaje de error personalizado que muestra una FaultRule.

Como práctica recomendada, debes definir respuestas claras de error desde tus API. De esa manera, ofreces información coherente y útil a tus clientes.

En el siguiente ejemplo de la política AssignMessage usa las etiquetas <Payload> y <StatusCode> para definir la respuesta de error personalizada que se envía al cliente en un error InvalidApiKey (consulta el ejemplo anterior de FaultRules).

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

La respuesta incluye los siguientes elementos:

  • La carga útil que contiene el mensaje de error y una dirección de correo electrónico para comunicarse con el equipo de asistencia.
  • El código de estado HTTP que se muestra en la respuesta.
  • La frase de motivo, que es una descripción breve del error.

Crea una DefaultFaultRule

Una DefaultFaultRule actúa como un controlador de excepciones para cualquier error que no se controla de forma explícita por otra FaultRule. Si las condiciones de todas las FaultRules no coinciden con el error, entonces DefaultFaultRule controla el error. Para habilitar el control de fallas predeterminado, agrega la etiqueta <DefaultFaultRule> como un elemento secundario de un ProxyEndpoint o TargetEndpoint.

Por ejemplo, la configuración TargetEndpoint a continuación define una DefaultFaultRule que invoca una política llamada 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>

Por lo general, se usa DefaultFaultRule a fin de mostrar un mensaje de error genérico para cualquier error inesperado, como un mensaje que contiene información de contacto para la asistencia técnica. Esta respuesta predeterminada tiene el doble propósito de proporcionar información intuitiva para el desarrollador y, al mismo tiempo, ofuscar las URL de backend o alguna otra información que pueda usarse a fin de comprometer el sistema.

Por ejemplo, puedes definir la siguiente política AssignMessage para mostrar un error genérico:

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

Incluye el elemento <AlwaysEnforce> en la etiqueta <DefaultFaultRule> a fin de ejecutar la DefaultFaultRule para cada error, incluso si ya se ejecutó otra FaultRule. La DefaultFaultRule es siempre la última FaultRule que se ejecutará:

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

Uno de los usos de la DefaultFaultRule es determinar el tipo de error que se produce cuando, de lo contrario, no puede determinarlo. Por ejemplo, si el proxy de API falla debido a un error que no puedes determinar, puedes usar DefaultFaultRule para invocar la siguiente política AssignMessage. Esta política escribe el valor fault.name en un encabezado llamado Unhandled-Fault en la respuesta:

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

Luego, puedes ver el encabezado en la herramienta de depuración o en la respuesta para ver qué causó el error.

Agrega el registro de mensajes a PostClientFlow

PostClientFlow es el único flujo que se ejecuta después de que el proxy ingresa el estado de error. Solo la política MessageLogging puede adjuntarse a este flujo, que se ejecuta después de que la respuesta se envía al cliente. Aunque adjuntar la política MessageLogging a este flujo no es un control de errores, puedes usarla para registrar información en caso de error. Debido a que se ejecuta sin importar si el proxy se realizó de forma correcta o no, puedes colocar las políticas de Message Logging en PostClientFlow y garantizar que siempre se ejecuten.

Controla de errores de políticas en el flujo actual

En los ejemplos que se mostraron hasta ahora, se usa una FaultRule en ProxyEndpoint o TargetEndpoint para controlar cualquier error de política como parte del estado de error. Esto se debe a que el valor predeterminado del elemento continueOnError de una política es false, lo que significa que cuando un error se produce en una política, el control se dirige al estado de error. Una vez en el estado de error, no puedes regresar el control a la canalización normal y, por lo general, muestras algún mensaje de error a la app que realiza la llamada.

Sin embargo, si estableces el elemento continueOnError en true para una política, el control permanecerá en el flujo actual y la siguiente política en la canalización se ejecuta después de la política que provocó el error. La ventaja de controlar el error en el flujo actual es que puedes tener una forma de recuperarse del error para completar el procesamiento de la solicitud.

A continuación, se muestra una política VerifyAPIKey llamada verify-api-key con el elemento continueOnError configurado como true:

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

Si falta la clave de API o no es válida, entonces la política VerifyAPIKey establece la variable oauthV2.verify-api-key.failed como true, pero el procesamiento continúa en el flujo actual.

Luego, debes agregar la política VerifyAPIKey como un paso en el PreFlow del 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>

Observa cómo el siguiente paso en PreFlow usa una condición para probar la existencia de un error. Si se produjo un error en la política de VerifyAPIKey, se ejecuta la política llamada FaultInFlow. De lo contrario, se omite la política FaultInFlow. La política FaultInFlow puede realizar muchas acciones, como registrar el error, intentar corregirlo o realizar alguna otra acción.

Activa un error mediante la política RaiseFault

Puedes usar la política RaiseFault en cualquier momento en un flujo para activar un error. Cuando se ejecuta una política RaiseFault, finaliza el flujo actual y se transfiere el control al estado de error.

Uno de los usos de la política RaiseFault es probar una condición específica que otra política podría no detectar. En el ejemplo anterior, agregaste una etiqueta <Condition> a una etiqueta <Step> de PreFlow que hizo que la política FaultInFlow se ejecutara si se cumplía la condición. Si FaultInFlow es una política RaiseFault, entonces controla las transferencias al estado de error. O bien, puedes insertar una política RaiseFault en un flujo para depurar y probar las fallas de las FaultRules.

Cuando una política RaiseFault genera un error, puedes usar la siguiente condición y falla de FaultRule para procesarla:

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

Ten en cuenta que la condición prueba una falla llamada RaiseFault. La política RaiseFault siempre establece el valor de fault.name como RaiseFault. También puedes establecer variables personalizadas dentro de una política RaiseFault. Si lo haces, podrás probar esas variables dentro de los elementos de la condición.

Control personalizado de códigos de error HTTP desde el servidor de destino

Los ejemplos que se muestran en las secciones anteriores se aplican a los errores que crean las políticas. Sin embargo, también puedes crear una respuesta personalizada para errores de nivel de transporte, es decir, errores HTTP que se muestran desde el servidor de destino. Para controlar la respuesta desde un error HTTP, configura un TargetEndpoint a fin de procesar los códigos de respuesta HTTP.

De forma predeterminada, Apigee trata a los códigos de respuesta HTTP en el rango 1xx-3xx como correcto, y los códigos de respuesta HTTP en el rango 4xx-5xx como falla. Eso significa que cualquier respuesta del servicio de backend con un código de respuesta HTTP 4xx-5xx invoca de forma automática el estado de error, que luego muestra un mensaje de error directamente al cliente solicitante.

Puedes crear controladores personalizados para cualquier código de respuesta HTTP. Por ejemplo, es posible que no quieras tratar todos los códigos de respuesta HTTP en el rango 4xx-5xx como "falla", sino solo 5xx, o que desees mostrar mensajes de error personalizados para los códigos de respuesta HTTP 400 y 500

En el siguiente ejemplo, usas la propiedad de success.codes para configurar TargetEndpoint a fin de tratar los códigos de respuesta HTTP 400 y 500 como éxito, junto con los códigos HTTP predeterminados. Si se trata de esos códigos como correctos, el TargetEndpoint se encarga del procesamiento del mensaje de respuesta, en lugar de invocar el estado de error:

<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 puedes ver en este ejemplo, puedes usar comodines para establecer la propiedad success.codes en un rango de valores.

Si configuras la propiedad de success.codes, se reemplazarán los valores predeterminados. Por lo tanto, si deseas agregar el código HTTP 400 a la lista de códigos de éxito predeterminados, configura esta propiedad de la siguiente manera:

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

Sin embargo, si solo quieres que el código HTTP 400 se trate como un código de éxito, configura la propiedad de la siguiente manera:

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

Ahora puedes definir controladores personalizados para que los códigos de respuesta HTTP 400 y 500 puedan mostrar un mensaje de respuesta personalizado a la app solicitante. El siguiente TargetEndpoint usa la política llamada ReturnError a fin de controlar los códigos de respuesta HTTP 400 y 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 configuración de TargetEndpoint hace que la política llamada ReturnError controle la respuesta cada vez que TargetEndpoint encuentra un código de respuesta HTTP de 400 O 500.

Taxonomía de fallas

Los servicios de API organizan fallas en las siguientes categorías y subcategorías.

Categoría Subcategoría Nombre de la falla Descripción
Mensajería Las fallas que se generan durante el flujo de mensajes (sin incluir fallas de políticas)
Fallas personalizadas {fault_name} Cualquier falla que el proxy de API controla de forma explícita mediante la política RaiseFault
Códigos de respuesta InternalServerError, NotFound Códigos de error HTTP 5xx, 4xx
Errores de enrutamiento NoRoutesMatched No se pudo seleccionar un TargetEndpoint con el nombre de una solicitud
Errores de clasificación NotFound Las fallas que genera un URI de solicitud que no coincide con ninguna BasePath de ProxyEndpoint (es decir, ningún proxy de API coincide con la URL en la solicitud de la app cliente)
Transporte Errores a nivel del transporte HTTP
Conectividad ConnectionRefused, ConnectionReset, ConnectionTimeout Se producen errores cuando se establecen conexiones de red o a nivel de transporte
Validaciones de las solicitudes ContentLengthMissing, HostHeaderMissing Las fallas se producen durante las verificaciones de semánticas en cada solicitud
Validaciones de respuestas Las fallas ocurren durante las verificaciones de semánticas en cada respuesta
Errores IO SSLHandshakeError, ReadTimeout, ReadError, WriteTimeout, WriteError, ChunkError Errores de lectura y escritura en extremos de cliente o de destino, tiempos de espera, errores de TLS/SSL y errores fragmentados
Sistema Errores de entorno de ejecución no definidos
Memoria OutOfMemory, GCOverLimit Fallas relacionadas con la memoria
Subproceso RogueTaskTerminated Fallas como la finalización de tareas inesperadas
Política Las fallas para cada tipo de política se definen en la Referencia de políticas.

Un error siempre va acompañado de una descripción de texto del motivo de la falla. Cuando el sistema genera una falla, se propaga un conjunto de atributos para ayudar a solucionar problemas. Una falla incluye la siguiente información:

  • Motivo
  • Atributos personalizados definidos por el usuario