Gestionar fallos

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 atienden las solicitudes de las aplicaciones. Por ejemplo, los proxies de API pueden tener problemas de red al comunicarse con los servicios de backend, las aplicaciones pueden presentar credenciales caducadas, los mensajes de solicitud pueden tener un formato incorrecto, etc.

Cuando se produce un error después de que una aplicación cliente llame a un proxy de API, se devuelve un mensaje de error al cliente. De forma predeterminada, el cliente recibe un mensaje de error a menudo críptico sin detalles ni orientación. Sin embargo, si quieres sustituir los mensajes de error predeterminados por mensajes personalizados más útiles e incluso enriquecerlos con elementos como encabezados HTTP adicionales, debes configurar el control de errores personalizado en Apigee.

El control de errores personalizado también te permite añadir funciones, como el registro de mensajes, cada vez que se produce un error.

Antes de hablar sobre cómo implementar el control de errores personalizado en tus proxies de API, es útil entender cómo se producen los errores y cómo reaccionan los proxies de API ante ellos.

Vídeos

Consulte los siguientes vídeos para obtener más información sobre la gestión de errores.

Vídeo Descripción
Introducción a la gestión de errores y los flujos de errores Consulta información sobre la gestión de errores y lo que ocurre cuando se produce un error en un proxy de API.
Gestionar errores con reglas de errores Consulta cómo gestionar los errores con reglas de errores.
Generar errores personalizados con la política RaiseFault Genera errores personalizados durante el tiempo de ejecución de la API con la política RaiseFault.
Definir reglas de error en los puntos de conexión de destino y del proxy de APIs Define reglas de errores en el proxy de API y en los puntos de conexión de destino, y conoce las diferencias.
Entender el orden de ejecución de las reglas de errores Conocer el orden de ejecución de las reglas de fallos en el proxy de API y los endpoints de destino.
Definir la regla predeterminada Define una regla de error predeterminada para gestionar los errores genéricos de tu API.

Cómo se producen los errores

Primero, veremos cómo se producen los errores. Saber cómo se producen los errores te ayuda a planificar las diferentes situaciones en las que quieras implementar el control de errores personalizado.

Errores automáticos

Un proxy de API genera un error automáticamente en las siguientes situaciones:

  • Una política genera un error. Por ejemplo, si una llamada a la API envía una clave caducada, la política VerifyAPIKey genera automáticamente un error. Si el número de llamadas a la API supera un límite determinado, la política Quota o la política SpikeArrest genera un error. (Consulta la referencia de errores de políticas para ver los tipos de errores que pueden generar las políticas).
  • Hay un problema en el flujo de mensajes del proxy de API, como un error de enrutamiento.
  • Se ha producido un fallo en el backend, como un error HTTP debido a fallos a nivel de protocolo, errores de TLS o SSL, o un servicio de destino no disponible.
  • Se produce un fallo a nivel del sistema, como una excepción de falta de memoria.

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

Errores personalizados

En situaciones en las que no se produce un error automático, puede que quieras generar un error personalizado. Por ejemplo, si una respuesta contiene la palabra unavailable o si el código de estado HTTP es superior a 201. Para ello, añade una política RaiseFault en el lugar adecuado del flujo de un proxy de API.

Puede añadir una política RaiseFault a un flujo de proxy de API del mismo modo que añade cualquier otra política. En el siguiente ejemplo de configuración de 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 RaiseFault y se produce un error.

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

Esto es solo para mostrarte que puedes generar errores personalizados. En la sección Diferencias entre FaultRules y la política RaiseFault se explica con más detalle 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 producen errores

Esto es lo que ocurre cuando un proxy genera un error.

Salir del flujo de procesamiento de proxies

Cuando un proxy de API detecta un error, independientemente de cómo se produzca, sale de la pipeline de flujo normal, entra en un estado de error y devuelve un mensaje de error a la aplicación cliente. Una vez que el proxy de API entra en el estado de error, no puede volver a la pipeline de flujo normal.

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

  1. Verificar clave de API
  2. Cuota
  3. De JSON a XML

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

Comprobar 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 devolver un mensaje de error predeterminado a la aplicación cliente:

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

En esencia, el proxy de API te ofrece la oportunidad de devolver un mensaje de error personalizado y activar otra lógica. Si el proxy no encuentra ninguna de esas secciones o existen, pero no se ha activado ningún error personalizado, el proxy envía su propio mensaje predeterminado generado por Apigee.

Ejemplo sencillo de gestión de errores

Empecemos con un ejemplo sencillo en el que una llamada a un proxy de API no contiene una clave de API obligatoria. De forma predeterminada, se devuelve la siguiente respuesta a la aplicación 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"}}}

Es posible que los usuarios de tu API puedan descifrar el mensaje de error, pero no es seguro. Además, muchos errores predeterminados son más sutiles y difíciles de descifrar.

Como desarrollador de APIs, debes cambiar este mensaje para que se ajuste a las necesidades de quien vaya a recibirlo, ya sea un desarrollador de aplicaciones iOS o un grupo de pruebas interno que tenga sus propios requisitos de formato de mensajes de error.

A continuación, se muestra un ejemplo básico de cómo crear un mensaje de error personalizado para gestionar este error. Para ello, se necesitan 1) una política que defina el mensaje personalizado y 2) una FaultRule que ejecute la política cuando el proxy entre en un estado de error.

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

Primero, cree una política que defina el mensaje de error personalizado. Puedes usar cualquier tipo de política, como una política AssignMessage, que puede definir una carga útil y encabezados HTTP opcionales, como el código de estado. La política AssignMessage es perfecta para ello. Te permite controlar la carga útil de los mensajes, definir un código de estado HTTP diferente y añadir encabezados HTTP.

No es necesario que asocie la política a un flujo. Solo tiene que crearla, tal como se describe en la sección Crear la política.

A continuación, se muestra un ejemplo de una política AssignMessage que hace lo siguiente:

  • Devuelve un mensaje JSON.
  • Define un código de estado HTTP (911, que es un código de estado obviamente inexistente para ilustrar la flexibilidad que tienes). El código de estado aparece en el encabezado HTTP.
  • Crea y rellena 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!</Header>
        </Headers>
    </Add>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Cuando se ejecute esta política, la respuesta a la aplicación cliente será similar a la siguiente. Compárala con la respuesta predeterminada que se ha mostrado 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!
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í, es un poco absurdo, pero te muestra lo que se puede hacer. Al menos ahora el desarrollador que recibe el mensaje sabe que se ha olvidado de incluir una clave de API como parámetro de consulta.

Pero ¿cómo se aplica esta política? En la siguiente sección se explica cómo hacerlo.

2. Crea el elemento <FaultRule> que activará la política.

En las secciones <ProxyEndpoint> o <TargetEndpoint> de la configuración del proxy, añada un bloque XML <FaultRules> que contenga una o varias secciones <FaultRule>. Cada FaultRule representa un error diferente que quieras gestionar. En este ejemplo sencillo, solo usaremos una FaultRule para mostrarte de qué se compone.

También debes añadir un <DefaultFaultRule> para proporcionar un mensaje de error general personalizado si no se ejecuta ninguna de tus 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 ProxyEndpoint. Es importante. Más adelante hablaremos sobre cómo colocar FaultRules en ProxyEndpoint y TargetEndpoint.
  • <Name>: el nombre de la política que se va a ejecutar. El nombre procede del atributo name de la política en el elemento superior, tal como se muestra en el ejemplo de 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 arriba abajo o de abajo arriba, difiere entre TargetEndpoint y ProxyEndpoint, como se describe en la sección Varias FaultRules y lógica de ejecución). Si no incluye una condición, FaultRule es automáticamente true. Pero no es una práctica recomendada. Cada FaultRule debe tener su propia condición.

  • <DefaultFaultRule>: si no se ejecuta ninguna FaultRule personalizada, se ejecuta <DefaultFaultRule>, que 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 un <Condition>, pero en la mayoría de los casos no se incluye ninguno, ya que se quiere que se ejecute pase lo que pase como último recurso.

    DefaultFaultRule se suele usar para devolver un mensaje de error genérico en caso de que se produzca un error inesperado. Por ejemplo, un mensaje que contenga información de contacto para asistencia técnica. Esta respuesta predeterminada tiene el doble propósito de proporcionar información útil para los desarrolladores y, al mismo tiempo, ofuscar las URLs de backend u otra información que se pueda usar para poner en peligro el sistema.

Múltiples FaultRules y lógica de ejecución

En la sección Ejemplo de gestión de errores sencilla, hemos usado un ejemplo sencillo de una sola FaultRule y una condición. En un proyecto de API real, con todos los errores que pueden producirse, es probable que tengas varias FaultRules y una DefaultFaultRule tanto en <ProxyEndpoint> como en <TargetEndpoint>. Sin embargo, en última instancia, 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 usa Apigee para gestionar FaultRules, desde cómo llega a una única FaultRule que ejecutar hasta cómo se gestionan las condiciones de los pasos internos cuando se activa su FaultRule. En esta sección también se explica cuándo definir FaultRules en <ProxyEndpoint> o en <TargetEndpoint>, y se describe la relación entre FaultRules y la política RaiseFault.

Ejecución de FaultRules

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

  1. Apigee evalúa las FaultRules en ProxyEndpoint o TargetEndpoint, en función de dónde se haya producido el error:
    • ProxyEndpoint: Apigee empieza por la parte inferior <FaultRule> del XML de configuración y va subiendo, evaluando el <Condition> de cada <FaultRule> (la condición externa y no las condiciones <Step> internas).
    • TargetEndpoint: Apigee empieza con el elemento superior <FaultRule> del XML de configuración y va hacia abajo, evaluando el <Condition> de cada <FaultRule> (la condición externa y no las condiciones <Step> internas).
  2. Ejecuta la primera FaultRule cuya condición sea verdadera. Si un elemento FaultRule no tiene ninguna condición, el valor predeterminado es true.
    • Cuando se ejecuta una FaultRule, todos los Steps que contiene se evalúan en orden, de arriba abajo en la configuración XML. Los pasos sin condiciones se ejecutan automáticamente (se ejecutan las políticas) y los pasos que tienen una <Condition> que se evalúa como se ejecutan (las condiciones que se evalúan como code no se ejecutan).

    • Si se ejecuta una FaultRule, pero no se ejecuta ningún paso de la FaultRule (porque sus condiciones se evalúan como code), se devuelve a la aplicación cliente el mensaje de error predeterminado generado por Apigee. El elemento <DefaultFaultRule> no se ejecuta porque Apigee ya ha ejecutado su FaultRule.

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

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

Ejecución de ProxyEndpoint

La evaluación de FaultRules de ProxyEndpoint se realiza de abajo arriba, por lo que debes empezar a leer la última FaultRule del siguiente ejemplo y seguir hacia arriba. Consulta DefaultFaultRule en último lugar.

<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

Las FaultRules de TargetEndpoint se evalúan de arriba abajo, así que empieza a leer la primera FaultRule del siguiente ejemplo y ve bajando. Consulta DefaultFaultRule en último lugar.

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

Como puede ver en el ejemplo anterior, el orden en el que coloque sus FaultRules es importante en función de si el error se produce en ProxyEndpoint o en TargetEndpoint.

Por ejemplo:

Orden de ProxyEndpoint Orden de TargetEndpoint

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

5. FaultRule 1: FALSE

4. FaultRule 2: TRUE

3. FaultRule 3: TRUE

2. FaultRule 4: FALSE

1. FaultRule 5: FALSE

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

1. FaultRule 1: FALSE

2. FaultRule 2: TRUE

3. FaultRule 3: TRUE

4. FaultRule 4: FALSE

5. FaultRule 5: FALSE

Políticas que se deben incluir

Puedes ejecutar cualquier política desde un FaultRule colocándola en Steps. Por ejemplo, puedes ejecutar una política AssignMessage para dar formato a una respuesta a la aplicación cliente y, a continuación, registrar un mensaje con la política MessageLogging. Las políticas se ejecutan en el orden en que las hayas colocado (de arriba abajo en el XML).

Las reglas de errores solo se activan cuando hay un error (sobre continueOnError)

Puede que el título parezca repetitivo, pero hay un matiz concreto que debes tener en cuenta en relación con un error de proxy que provoca que un proxy de API entre en un estado de error o, mejor dicho, no entre en un estado de error: el atributo continueOnError de una política.

En resumen, un proxy de API evalúa <FaultRules> y <DefaultFaultRule> solo si el proxy ha entrado en un estado de error. Esto significa que, aunque una condición de FaultRule se evalúe como verdadera, no se activará si el proxy no está en un estado de error.

Sin embargo, aquí tienes un ejemplo de un error que se produce y el proxy no entra en un estado de error. En cualquier política, puedes definir un atributo en el elemento superior llamado continueOnError. Este atributo es muy importante en lo que respecta a la gestión de errores, ya que determina si el proxy entra en un estado de error si la política falla. En la mayoría de los casos, te recomendamos que mantengas el valor predeterminado continueOnError="false", que hace que el proxy pase a un estado de error si la política falla y se active tu gestión de errores personalizada. Sin embargo, si continueOnError="true" (por ejemplo, si no quieres que el fallo de una llamada de servicio detenga la ejecución del proxy), el proxy no pasará a un estado de error si falla esa política y no tendrá en cuenta tus FaultRules.

Para obtener información sobre cómo registrar errores cuando se produce un continueOnError="true", consulta Gestionar errores de políticas en el flujo actual.

Dónde definir FaultRules: ProxyEndpoint o TargetEndpoint

Cuando un proxy de API experimenta un error, este se produce en el <ProxyEndpoint> (solicitud de la aplicación cliente o respuesta a ella) o en el <TargetEndpoint> (solicitud al servicio de destino o respuesta de este). Apigee busca FaultRules en el lugar donde se produce ese error.

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

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

Comparación entre FaultRules y la política RaiseFault

Las reglas de fallo y la política RaiseFault pueden parecer formas alternativas de gestionar los fallos, y en cierto modo es así. Pero también funcionan en conjunto. En esta sección se explica la relación entre ambos. Comprender esta relación te ayudará a diseñar la gestión de errores, sobre todo si quieres usar ambos.

Este es un breve resumen de los aspectos importantes de este concepto:

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

  • La política RaiseFault es una forma de poner un proxy de API en un estado de error cuando no se habría producido ningún error.

    Por ejemplo, si quieres generar un error si el código de estado HTTP de la respuesta del servicio de destino es superior a 200, añade una política RaiseFault al flujo de respuesta. Sería algo parecido a esto:

    <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 aplicación cliente.

¿Qué ocurre cuando una política RaiseFault activa un error, lo que provoca que el proxy entre en un estado de error, que potencialmente ejecuta una FaultRule? Aquí es donde las cosas pueden complicarse un poco. Si la política RaiseFault devuelve un mensaje de error y se activa una FaultRule que devuelve un mensaje de error, ¿qué se devuelve a la aplicación cliente?

  • Como FaultRule o DefaultFaultRule se ejecutan después de la política RaiseFault, los datos de respuesta de FaultRule tienen prioridad.
  • Los datos de respuesta de la política RaiseFault (código de estado o carga útil del mensaje) se utilizan si FaultRule o DefaultFaultRule no definen esos datos.
  • Si tanto la política RaiseFault como FaultRule añaden encabezados HTTP personalizados, ambos se incluirán en la respuesta. Si se duplican los nombres de los encabezados, se crea un encabezado con varios valores.

A continuación se muestra un ejemplo de lo que se define en una política RaiseFault y en una FaultRule, y lo que se devuelve a la aplicación cliente. Los ejemplos se han diseñado para que sean breves, no para que representen las prácticas recomendadas.

Qué se define en una política RaiseFault y en una FaultRule.

La aplicación cliente recibe:

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

<- La política de reglas de errores establece este valor:

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

<- La política RaiseFault establece este valor:

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

Crear condiciones

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

Para poner en contexto el resto de esta sección, aquí tienes una regla de error de ejemplo que tiene una condición FaultRule externa y una condición 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>

Variables específicas de los errores de políticas

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 falle, 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, la variable de flujo fault.name se asigna al valor FailedToResolveAPIKey.

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

Por lo tanto, la condición sería la siguiente:

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

Consulta la referencia de errores de políticas para ver una lista de errores de 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. En el caso de los espacios de nombres de las políticas, consulta las variables de flujo de cada tema de referencia de política.

Otras variables disponibles

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

  • Las variables de la política que ha fallado.
  • Las variables de mensaje HTTP que existen en el momento del fallo. Por ejemplo, si se produce un error en la respuesta, una FaultRule en <TargetEndpoint> podría usar datos HTTP response.status.code, message.content, error.content, etc. O bien, si falla una política de cuota, puedes usar la variable ratelimit.{quota_policy_name}.exceed.count. Utilice la herramienta de depuración y la referencia de políticas para saber qué variables y datos HTTP están disponibles.

Más información

Prácticas recomendadas para la gestión de errores

La gestión de errores es una tarea de diseño arquitectónico importante para el desarrollo de proxies de API. Es importante que te tomes tu tiempo para averiguar cómo y cuándo vas a gestionar los errores, determinar qué mensajes de error vas a mostrar y diseñar los formatos de los mensajes de error. Cuando hayas resuelto estos aspectos (o mientras lo haces), utiliza estas prácticas recomendadas para implementar la gestión de errores.

A continuación, se indican algunas prácticas recomendadas para diseñar y crear la gestión de errores:

  • En FaultRules, puedes especificar cualquier tipo de política. El patrón más habitual es usar la política AssignMessage para definir elementos específicos en la respuesta de error pendiente. También puedes usar AssignMessage para definir variables que se usen con otros fines, por ejemplo, para variables a las que hacen referencia las políticas de registro que se ejecutan en PostClientFlow o en FlowHooks. También puedes registrar un mensaje, por ejemplo, con la política MessageLogging o la política ServiceCallout, si quieres registrar errores específicos en condiciones de fallo concretas.
  • No especifiques políticas RaiseFault como pasos dentro de una FaultRule. Es mejor usar políticas AssignMessage para definir o modificar elementos de los mensajes, como la carga útil, las cabeceras o el código de estado.
  • En cada FaultRule o en todos los FaultRule, excepto el último evaluado, proporcione un outer <Condition> adjunto como elemento secundario del elemento <FaultRule>. La condición de ejecución de una FaultRule sin una condición explícita especificada se evaluará implícitamente como true. Un elemento <Condition> adjunto como elemento secundario de un elemento <Step> no se usa para determinar si la condición de ejecución de FaultRule se evalúa como true o false. Las condiciones de los pasos solo se evalúan después de que Apigee ejecute la FaultRule que las contiene. En una FaultRule, es habitual tener varios elementos Step con políticas AssignMessage (u otras), cada uno con una condición Step.

  • Para gestionar errores en varias políticas del mismo tipo (por ejemplo, varias políticas de cuota), cree una FaultRule por cada error de política que sea probable que reciba y, a continuación, distinga entre los distintos errores con las condiciones asociadas a los pasos. Por ejemplo, crea una FaultRule para gestionar un error en las políticas de cuota, como QuotaViolation, y otra FaultRule para InvalidApiKey. (Consulta la referencia de errores de políticas para obtener información sobre los errores de políticas. A medida que descubras errores adicionales que deban gestionarse, podrás volver más adelante y añadirlos a tus FaultRules. No hay problema en que sea iterativo, aunque requiere volver a implementar el proxy. Este enfoque te permite detectar el mismo tipo de error independientemente de la política que lo genere, lo que hace que tu archivo XML de FaultRules sea eficiente.

    Las condiciones de los pasos internos te ofrecen un control más preciso. Por ejemplo, si aplicas tanto la cuota de desarrollador individual como la cuota global con dos políticas en tu flujo de solicitudes, define la condición externa de FaultRule para que se active cuando se produzca el error QuotaViolation (que se genera cuando se supera la cuota en cualquiera de los casos). A continuación, define las condiciones del paso para evaluar las variables exceed.count específicas de ambas políticas de cuota. Solo se envía al cliente el error pertinente (exceso de cuota de desarrollador o exceso de cuota global). Este es 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 debate sobre la gestión de errores de políticas.

  • Para gestionar los errores cuando usas una sola política de un tipo, considera la posibilidad de usar una sola regla de error que se ejecute cuando falle esa política e incluye varios pasos que se correspondan con cada error posible. De esta forma, el XML es más sencillo, ya que se usa una sola FaultRule en lugar de varias (una por cada tipo de error). Por ejemplo, puede especificar que se ejecuten diferentes pasos de la política AssignMessage en distintas condiciones, como se muestra a continuación:

    <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>
  • Añada FaultRules en los lugares donde se producirán los errores (lado del cliente <ProxyEndpoint> o lado de destino <TargetEndpoint>). Incluya FaultRules para cada política que aparezca en cada ubicación.
  • Cuando se usan políticas RaiseFault junto con FaultRules, coordina los datos de respuesta que se envían cuando tanto la política RaiseFault como una FaultRule devuelven datos. Por ejemplo, si tienes una política RaiseFault que define el código de estado HTTP, no configures también un paso AssignMessage en una FaultRule que restablezca el código de estado. Lo peor que puede ocurrir es que se devuelva el código de estado predeterminado a la aplicación cliente.

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

    • No se ha ejecutado ninguna otra FaultRule. Un caso especial es cuando no hay ningún elemento <FaultRules> configurado.
    • Si el elemento secundario <AlwaysEnforce> de <DefaultFaultRule> es true.

    También puede especificar un elemento <Condition> en un elemento <DefaultFaultRule>. Puedes hacerlo para excluir su ejecución en función de algún estado de la solicitud o de un mensaje de error pendiente, por ejemplo, si falta o está presente un encabezado específico.

    Usa un <DefaultFaultRule> con <AlwaysEnforce> definido como true si tienes una o varias políticas que quieres que el proxy siempre lleve a cabo, independientemente de si se ha ejecutado una FaultRule anterior. Un posible caso práctico: supongamos que quieres insertar un encabezado en la respuesta en todos los casos, independientemente de si la solicitud del proxy ha provocado un error o no, y de si el error se ha gestionado previamente o no. A continuación, adjuntarías una política AssignMessage adecuada en la sección <PostFlow>/<Response> y también adjuntarías la misma política en <DefaultFaultRule> con <AlwaysEnforce> definido como true.

Patrón para la gestión de errores centralizada y reutilizable

Un patrón de gestión de errores para proxies de Apigee describe un patrón para la gestión de errores centralizada sin duplicación de código.

Crear FaultRules

Para añadir una FaultRule, debes editar la configuración XML de ProxyEndpoint o TargetEndpoint. Puedes usar la interfaz de usuario de Apigee para hacer este cambio en el panel Código de la vista Desarrollar de un proxy de API, o bien editar el archivo XML que define el ProxyEndpoint o el TargetEndpoint.

Si creas FaultRules en la interfaz de usuario de Apigee, primero crea las políticas que quieras ejecutar y, a continuación, añádelas a la configuración de FaultRule. Si intentas guardar una FaultRule que haga referencia a una política que aún no se ha creado, se producirá un error en la interfaz de usuario.

Añadir políticas a un FaultRule

Aunque puedes incluir cualquier política en FaultRule, lo habitual es usar la política AssignMessage para generar un mensaje de respuesta personalizado en caso de error. AssignMessage te permite configurar una respuesta HTTP con una carga útil, un código de estado HTTP y encabezados.

En el siguiente ejemplo 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 de ambiente, en función de dónde se adjunte la política.

Ahora puedes usar esta política en tu elemento FaultRule. Fíjate en cómo haces referencia a la política AssignMessage por su nombre en 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 aplicación presente una clave de API no válida.

Puedes ejecutar varias políticas en un elemento 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 AssignMessage o cualquier otra política de FaultRule. Ten en cuenta que el procesamiento de FaultRule se detiene inmediatamente si se produce alguna de estas situaciones:

  • Cualquier política de FaultRule provoca un error
  • Cualquiera de las políticas de FaultRule es de tipo RaiseFault

Define el mensaje de error personalizado que devuelve una FaultRule.

Te recomendamos que definas respuestas de error claras en tus APIs. De esta forma, podrás ofrecer información coherente y útil a tus clientes.

En el siguiente ejemplo de política AssignMessage se usan las etiquetas <Payload> y <StatusCode> para definir la respuesta de error personalizada que se envía al cliente cuando se produce 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>

Esta respuesta incluye lo siguiente:

  • La carga útil que contiene el mensaje de error y una dirección de correo para contactar con el equipo de Asistencia.
  • El código de estado HTTP devuelto en la respuesta.

Crear un DefaultFaultRule

Una DefaultFaultRule actúa como controlador de excepciones para cualquier error que no se gestione de forma explícita mediante otra FaultRule. Si las condiciones de todas las FaultRules no coinciden con el error, la DefaultFaultRule gestiona el error. Para habilitar la gestión de errores predeterminada, añade la etiqueta <DefaultFaultRule> como elemento secundario de un ProxyEndpoint o un TargetEndpoint.

Por ejemplo, la configuración de TargetEndpoint que se muestra 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>

DefaultFaultRule se suele usar para devolver un mensaje de error genérico en caso de que se produzca un error inesperado, como un mensaje que contenga información de contacto para obtener asistencia técnica. Esta respuesta predeterminada tiene el doble propósito de proporcionar información útil para los desarrolladores y, al mismo tiempo, ofuscar las URLs de backend u otra información que pueda usarse para poner en peligro el sistema.

Por ejemplo, define la siguiente política AssignMessage para devolver 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> para ejecutar DefaultFaultRule en cada error, incluso si ya se ha ejecutado otra FaultRule. DefaultFaultRule siempre es la última FaultRule que se ejecuta:

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

Una de las funciones de DefaultFaultRule es determinar el tipo de error que se produce cuando no se puede determinar de otro modo. Por ejemplo, si tu 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>

A continuación, puedes ver el encabezado en la herramienta de depuración o en la respuesta para ver qué ha provocado el error.

Añadir registro de mensajes a PostClientFlow

PostClientFlow es el único flujo que se ejecuta después de que el proxy entre en el estado de error. Solo se puede adjuntar la política MessageLogging a este flujo, que se ejecuta después de que se envíe la respuesta al cliente. Aunque adjuntar la política MessageLogging a este flujo no es técnicamente un control de errores, puedes usarla para registrar información en caso de que se produzca un error. Como se ejecuta independientemente de si el proxy se ha completado correctamente o no, puede colocar políticas de registro de mensajes en PostClientFlow y tener la garantía de que siempre se ejecutan.

Gestionar errores de políticas en el flujo actual

En todos los ejemplos que hemos visto hasta ahora, se usa una FaultRule en ProxyEndpoint o TargetEndpoint para gestionar los errores de las políticas 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 se produce un error en una política, el control se dirige al estado de error. Una vez que se ha producido un error, no puedes devolver el control a la canalización normal y, por lo general, devuelves algún tipo de mensaje de error a la aplicación que ha llamado.

Sin embargo, si asignas el valor true al elemento continueOnError de una política, el control se mantiene en el flujo actual y la siguiente política de la cadena se ejecuta después de la política que ha provocado el error. La ventaja de gestionar el error en el flujo actual es que puedes tener una forma de recuperarte 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 definido 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, la política VerifyAPIKey asigna el valor true a la variable oauthV2.verify-api-key.failed, pero el procesamiento continúa en el flujo actual.

A continuación, añade la política VerifyAPIKey como paso en el PreFlow de 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>

Fíjate en que el siguiente paso de PreFlow usa una condición para comprobar si hay un error. Si se ha producido un error en la política VerifyAPIKey, se ejecutará la política llamada FaultInFlow. De lo contrario, se omitirá la política FaultInFlow. La política FaultInFlow puede hacer muchas cosas, como registrar el error, intentar corregirlo o realizar alguna otra acción.

Activar un error mediante la política RaiseFault

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

Una de las aplicaciones de la política RaiseFault es comprobar si se cumple una condición específica que otra política no detecta. En el ejemplo anterior, has añadido una etiqueta <Condition> a una etiqueta PreFlow <Step> que ha provocado que se ejecute la política FaultInFlow si se cumple la condición. Si FaultInFlow es una política RaiseFault, el control se transfiere al estado de error. También puede insertar una política RaiseFault en un flujo para depurar y probar sus FaultRules.

Cuando una política RaiseFault activa un error, puedes usar la siguiente FaultRule y condición para procesarlo:

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

Ten en cuenta que la condición busca un error llamado RaiseFault. La política RaiseFault siempre asigna el valor RaiseFault a fault.name. También puede definir variables personalizadas en una política RaiseFault. Si lo haces, podrás probar esas variables en los elementos Condition.

Gestión personalizada de los códigos de error HTTP del servidor de destino

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

De forma predeterminada, Apigee trata los códigos de respuesta HTTP del intervalo 1xx-3xx como correctos y los códigos de respuesta HTTP del intervalo 4xx-5xx como incorrectos. Esto significa que cualquier respuesta del servicio backend con un código de respuesta HTTP 4xx-5xx invoca automáticamente el estado de error, que devuelve un mensaje de error directamente al cliente que ha enviado la solicitud.

Puedes crear controladores personalizados para cualquier código de respuesta HTTP. Por ejemplo, puede que no quieras tratar todos los códigos de respuesta HTTP del intervalo 4xx-5xx como "error", sino solo 5xx, o que quieras devolver mensajes de error personalizados para los códigos de respuesta HTTP 400 y 500.

En el siguiente ejemplo, se usa la propiedad success.codes para configurar TargetEndpoint de forma que trate los códigos de respuesta HTTP 400 y 500 como correctos, junto con los códigos HTTP predeterminados. Al tratar esos códigos como correctos, TargetEndpoint se encarga de procesar el 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 puede ver en este ejemplo, puede usar comodines para asignar a la propiedad success.codes un intervalo de valores.

Si asignas un valor a la propiedad success.codes, se sobrescribirán los valores predeterminados. Por lo tanto, si quiere añadir el código HTTP 400 a la lista de códigos de éxito predeterminados, defina 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 correcto, define la propiedad de la siguiente manera:

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

Ahora puede definir controladores personalizados para los códigos de respuesta HTTP 400 y 500 para devolver un mensaje de respuesta personalizado a la aplicación que realiza la solicitud. El siguiente TargetEndpoint usa la política llamada ReturnError para gestionar 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 gestione la respuesta cuando TargetEndpoint detecte un código de respuesta HTTP 400 O 500.

Taxonomía de fallos

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

Categoría Subcategoría Nombre del error Descripción
Mensajes Errores que se producen durante el flujo de mensajes (sin incluir los errores de políticas)
Errores personalizados {fault_name} Cualquier error gestionado explícitamente por el proxy de API mediante la política RaiseFault
Códigos de respuesta InternalServerError, NotFound Códigos de error HTTP 5xx y 4xx
Errores de enrutamiento NoRoutesMatched Failure in selecting a named TargetEndpoint for a request
Errores de clasificación NotFound Errores causados por una URI de solicitud que no coincide con ningún BasePath de ninguna configuración de ProxyEndpoint (es decir, ninguna API proxy coincide con la URL de la solicitud de la aplicación cliente)
Transporte Errores de nivel de transporte HTTP
Conectividad ConnectionRefused, ConnectionReset, ConnectionTimeout Se producen errores al establecer conexiones de red o de nivel de transporte
Solicitar validaciones ContentLengthMissing, HostHeaderMissing Se producen errores durante las comprobaciones semánticas en cada solicitud
Validaciones de respuestas Se producen errores durante las comprobaciones semánticas en cada respuesta
Errores de E/S SSLHandshakeError, ReadTimeout, ReadError, WriteTimeout, WriteError, ChunkError Errores de lectura o escritura en los endpoints de cliente o de destino, tiempos de espera agotados, errores de TLS/SSL y errores de fragmentación
Sistema Errores de tiempo de ejecución indefinidos
Memoria OutOfMemory, GCOverLimit Errores relacionados con la memoria
Conversación RogueTaskTerminated Errores, como la finalización de tareas descontroladas
Política Los errores de cada tipo de política se definen en la referencia de políticas.

Los errores siempre van acompañados de una descripción textual del motivo del fallo. Cuando el sistema genera un error, se rellenan una serie de atributos para ayudar a solucionar el problema. Un fallo incluye la siguiente información:

  • Motivo
  • Atributos personalizados definidos por el usuario