Nombres de error Reintento después de un error Estados alternativos Ejemplos de uso de reintento y uso de captura

Administración de errores en Step Functions

Cualquier estado puede registrar errores en tiempo de ejecución. Los errores pueden producirse por varias razones:

Problemas con la definición de la máquina de estado (por ejemplo, un estado Choice no tiene ninguna regla)
Errores de tareas (por ejemplo, una excepción de una función de Lambda)
Problemas transitorios (por ejemplo, eventos relacionados con las particiones de red)

De forma predeterminada, cuando un estado registra un error, AWS Step Functions hace que la ejecución falle por completo.

Nombres de error

Step Functions identifica errores en Amazon States Language utilizando cadenas que distinguen mayúsculas, lo que se conoce comonombres de error. Amazon States Language define un conjunto de cadenas integradas que designan errores conocidos, que comienzan por laStates.prefijo.

States.ALL

Comodín que coincide con cualquier nombre de error conocido.

nota

Este tipo de error no puede catch elStates.DataLimitExceededtipo de error de terminal y tipos de error en tiempo de ejecución. Para obtener más información acerca de estos tipos de error, consulteStates.DataLimitExceededyStates.Runtime.

States.BranchFailed

Una rama de unParallelestado falló.

States.DataLimitExceeded

UNAStates.DataLimitExceededse lanzará una excepción para lo siguiente:

Cuando la salida de un conector es mayor que la cuota de tamaño de carga útil.
Cuando la salida de un estado es mayor que la cuota de tamaño de carga útil.
Cuándo, despuésParametersprocesamiento, la entrada de un estado es mayor que la cuota de tamaño de la carga útil.

Para obtener más información sobre las cuotas de, consulteCuotas.

nota

Se trata de un error de terminal que no puede ser detectado por elStates.ALLtipo de error.

States.HeartbeatTimeout

UNATaskestado no puede enviar un latido durante un período mayor que elHeartbeatSecondsValor .

nota

Este error solo está disponible dentro delCatchyRetry.

States.IntrinsicFailure

Este error se produce cuando falla el intento de invocar una función intrínseca dentro de una plantilla de carga útil.

States.NoChoiceMatched

Este error de tiempo de ejecución se produce si unChoicestate no coincide con la entrada con las condiciones definidas en la Regla de elección y no se especifica ninguna transición predeterminada.

States.ParameterPathFailure

Este error se produce cuando se encuentra dentro de un estadoParameters, un intento de sustituir un campo cuyo nombre termina en.$el uso de una ruta falla.

States.Permissions

Estado Task que registró un error porque no tenía privilegios suficientes para ejecutar el código especificado.

States.ResultPathMatchFailure

EstadoResultPathno se puede aplicar a la entrada recibida por el estado.

States.Runtime

Error de ejecución causado por una excepción que no se ha podido procesar. La causa de estos problemas suelen ser errores en el tiempo de ejecución, como intentar aplicar InputPath o OutputPath a una carga JSON nula. Un error States.Runtime no se puede volver a intentar y siempre provocará que se produzca un error en la ejecución. Un reintento o captura de States.ALL no capturará los errores de States.Runtime.

States.TaskFailed

Estado Task que registró un error durante la ejecución. Cuando se utiliza en un reintento o catch,States.TaskFailedactúa como un comodín que coincide con cualquier nombre de error conocido, excepto paraStates.Timeout.

States.Timeout

Estado Task que se ejecuta durante más tiempo que el valor TimeoutSeconds o que no puede enviar un latido durante un período mayor que el valor de HeartbeatSeconds.

Los estados pueden notificar errores con otros nombres. Sin embargo, estos nombres no pueden comenzar por el prefijo States.

Utilice la práctica recomendada de asegurarse de que el código de producción controle las excepciones del servicio de AWS Lambda (Lambda.ServiceException y Lambda.SdkClientException). Para obtener más información, consulte Manejar las excepciones de servicio Lambda.

nota

Los errores no controlados en Lambda se notifican comoLambda.Unknownen la salida de error. Entre ellas se incluyen out-of-memory errores y tiempos de espera de funciones. Puedes emparejar enLambda.Unknown,States.ALL, o bienStates.TaskFailedpara manejar estos errores. Cuando Lambda alcanza el número máximo de invocaciones, el error esLambda.TooManyRequestsException. Para obtener más información acerca de LambdaHandledyUnhandlederrores, consulteFunctionErroren laAWS LambdaGuía para desarrolladores.

Reintento después de un error

Los estados Task y Parallel pueden tener un campo llamado Retry, cuyo valor debe ser una matriz de objetos, denominados reintentadores. Cada reintentador representa un número determinado de reintentos, que normalmente aumentan en intervalos de tiempo.

nota

Los reintentos se tratan como transiciones de estado. Para obtener información sobre cómo afectan las transiciones de estado a la facturación, consultePrecios de Step Functions.

Los reintentadores contienen los siguientes campos.

ErrorEquals (Obligatorio): Matriz no vacía de cadenas que coinciden con nombres de error. Cuando un estado registra un error, Step Functions lo analiza a través de los reintentadores. Cuando el nombre de error aparece en esta matriz, se implementa la política de reintentos que se describe en este reintentador.
IntervalSeconds (opcional): Entero que representa el número de segundos antes del primer reintento (1de forma predeterminada).IntervalSecondstiene un valor máximo de99999999.
MaxAttempts (opcional): Entero positivo que representa el número máximo de reintentos (el valor predeterminado es 3). Si el error se repite más veces de las especificadas, se interrumpen los reintentos y se reanuda el control normal de errores. Valor de0especifica que no se efectúan reintentos en el error o errores.MaxAttemptstiene un valor máximo de99999999.
BackoffRate (opcional): Multiplicador según el cual aumenta el intervalo de reintentos durante cada fase (el valor predeterminado es 2.0).

Este ejemplo de Retry realiza dos fases de reintentos después de esperar a 3 y 4,5 segundos.


"Retry": [ {
   "ErrorEquals": [ "States.Timeout" ],
   "IntervalSeconds": 3,
   "MaxAttempts": 2,
   "BackoffRate": 1.5
} ]

El nombre reservado States.ALL que aparece en el campo ErrorEquals de un reintentador es un nombre comodín que coincide con cualquier nombre de error. Debe aparecer solo en la matriz ErrorEquals y debe aparecer en el último reintentador de la matriz Retry. NombreStates.TaskFailedtambién actúa como comodín y coincide con cualquier error, excepto porStates.Timeout.

En este ejemplo del campo Retry, se reintentan todos los errores excepto States.Timeout.


"Retry": [ {
   "ErrorEquals": [ "States.Timeout" ],
   "MaxAttempts": 0
}, {
   "ErrorEquals": [ "States.ALL" ]
} ]

Escenarios de reintentos complejos

Los parámetros de un reintentador se aplican a todas las visitas que se realizan a dicho reintentador durante la ejecución de un único estado.

Supongamos que tenemos el siguiente estado Task.


"X": {
   "Type": "Task",
   "Resource": "arn:aws:states:us-east-1:123456789012:task:X",
   "Next": "Y",
   "Retry": [ {
      "ErrorEquals": [ "ErrorA", "ErrorB" ],
      "IntervalSeconds": 1,
      "BackoffRate": 2.0,
      "MaxAttempts": 2
   }, {
      "ErrorEquals": [ "ErrorC" ],
      "IntervalSeconds": 5
   } ],
   "Catch": [ {
      "ErrorEquals": [ "States.ALL" ],
      "Next": "Z"
   } ]
}

Esta tarea falla cinco veces seguidas y devuelve estos nombres de error: ErrorA, ErrorB, ErrorC, ErrorB y ErrorB. Como resultado, se produce lo siguiente:

Los dos primeros errores coinciden con el primer reintentador y produce esperas de 1 y 2 segundos.
El tercer error coincide con el segundo reintentador y produce una espera de 5 segundos.
El cuarto error coincide con el primer reintentador y produce una espera de 4 segundos.
El cuarto error también coincide con el primer reintentador. Sin embargo, ya ha alcanzado su máximo de dos reintentos (MaxAttempts) para ese error en particular (ErrorB), de modo que el recuperador falla y la ejecución se redirige alZestado a través delCatch.
El quinto error también coincide con el primer reintentador. Sin embargo, ya ha alcanzado el máximo de dos reintentos (MaxAttempts) para ese error específico (ErrorB), por lo que falla y la ejecución se redirige al estado Z a través del campo Catch.

Estados alternativos

Task,MapyParallelstate puede tener un campo llamadoCatch. El valor de este campo debe ser una matriz de objetos, denominados receptores.

Un receptor contiene los siguientes campos.

ErrorEquals (Obligatorio): Matriz no vacía de cadenas que coinciden con nombres de error, especificados exactamente como se indicaron en el campo del mismo nombre del reintentador.
Next (Obligatorio): Cadena que debe coincidir exactamente con uno de los nombres de estado de la máquina de estado.
ResultPath (opcional): Ruta que determina qué datos de entrada se envían al estado especificado en el campo Next.

Cuando un estado registra un error y no hayRetryo si los reintentos no son capaces de resolver el error, Step Functions lo analiza a través de los receptores en el orden en que aparecen en la matriz. Cuando el nombre de error aparece en el valor del campo ErrorEquals de un receptor, la máquina de estado adopta el estado especificado en el campo Next.

El nombre reservado States.ALL que aparece en el campo ErrorEquals de un receptor es un nombre comodín que coincide con cualquier nombre de error. Debe aparecer solo en la matriz ErrorEquals y debe aparecer en el último receptor de la matriz Catch. NombreStates.TaskFailedtambién actúa como comodín y coincide con cualquier error, excepto porStates.Timeout.

En el siguiente ejemplo deCatchtransiciones de campo al estado identificadoRecoveryStatecuando una función Lambda produce una excepción Java no controlada. De lo contrario, el campo cambia al estado EndState.


"Catch": [ {
   "ErrorEquals": [ "java.lang.Exception" ],
   "ResultPath": "$.error-info",
   "Next": "RecoveryState"
}, {
   "ErrorEquals": [ "States.ALL" ],
   "Next": "EndState"
} ]

nota

Cada receptor puede especificar varios errores que deben controlarse.

Salida de error

Cuando Step Functions adopta el estado especificado en un nombre de catch, por lo general, el objeto contiene el campoCause. El valor de este campo es una descripción del error en lenguaje natural. Este objeto se conoce como salida de error.

En este ejemplo, el primer receptor contiene un campo ResultPath. Funciona de manera parecida a un campo ResultPath del nivel superior del estado, lo que genera dos posibilidades:

Toma los resultados de la ejecución del estado y sobrescribe una parte de los datos de entrada del estado (o todos ellos).
Toma los resultados y los agrega a los datos de entrada. En el caso de los errores controlados por un receptor, el resultado de la ejecución del estado es la salida de error.

Por tanto, en el primer receptor de este ejemplo, la salida de error se agrega a los datos de entrada como un campo llamado error-info (si no hay ningún campo con este nombre en los datos de entrada). A continuación, toda la entrada se envía a RecoveryState. En el segundo receptor, la salida de error sobrescribe los datos de entrada y solo se envía la salida de error a EndState.

nota

Si no se especifica el campo ResultPath, este se establece de forma predeterminada en $, que selecciona y sobrescribe toda la entrada.

Cuando un estado tiene ambosRetryyCatch, Step Functions utiliza primero alguno de los reintentadores correspondientes y, posteriormente, solo aplica la transición del receptor coincidente si la política de reintentos no puede resolver el error.

Causa cargas útiles e integraciones de servicios

Un receptor devuelve una carga útil de cadena como salida. Cuando se trabaja con integraciones de servicios como Amazon Athena oAWS CodeBuild, es posible que desee convertir laCausecadena a JSON. En el siguiente ejemplo de estado Pass con funciones intrínsecas se muestra cómo convertir una cadena Cause en JSON.


"Handle escaped JSON with JSONtoString": {
  "Type": "Pass",
  "Parameters": {
    "Cause.$": "States.StringToJson($.Cause)"
  },
  "Next": "Pass State with Pass Processing"
},

Ejemplos de uso de reintento y uso de captura

Las máquinas de estado que se definen en los ejemplos siguientes presuponen la existencia de dos funciones de Lambda: una que siempre registra errores y otra que espera lo suficiente para permitir que transcurra el tiempo de espera especificado en la máquina de estado.

Esta es una definición de una función Lambda de Node.js que siempre registra errores y devuelve el mensajeerror. En los ejemplos de máquinas de estado siguientes, esta función de Lambda se llamaFailFunction. Para obtener información acerca de cómo crear una función de Lambda, consultePaso 1: Creación de una función Lambdasección.


exports.handler = (event, context, callback) => {
    callback("error");
};

Esta es una definición de una función Lambda de Node.js que se suspende durante 10 segundos. En los ejemplos de máquinas de estado siguientes, esta función de Lambda se llamasleep10.

nota

Cuando cree esta función de Lambda en la consola de Lambda, recuerde cambiar laTimeout (Tiempo de espera):Valor en laConfiguración avanzadasección de 3 segundos (predeterminado) a 11 segundos.


exports.handler = (event, context, callback) => {
    setTimeout(function(){
    }, 11000);
};

Gestión de un error mediante reintento

Esta máquina de estado utiliza un campo Retry para recuperar una función que no se ejecuta correctamente y que devuelve el nombre de error HandledError. La función se reintenta dos veces, con un retardo exponencial entre los reintentos.


{
   "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:us-east-1:123456789012:function:FailFunction",
         "Retry": [ {
            "ErrorEquals": ["HandledError"],
            "IntervalSeconds": 1,
            "MaxAttempts": 2,
            "BackoffRate": 2.0
         } ],
      "End": true
      }
   }
}

Esta variante utiliza el código de error predefinidoStates.TaskFailed, que coincide con cualquier error que una función de Lambda puede devolver.


{
   "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:us-east-1:123456789012:function:FailFunction",
         "Retry": [ {
            "ErrorEquals": ["States.TaskFailed"],
            "IntervalSeconds": 1,
            "MaxAttempts": 2,
            "BackoffRate": 2.0
         } ],
         "End": true
      }
   }
}

nota

Es recomendable que las tareas que hacen referencia a una función de Lambda controlen las excepciones del servicio de Lambda. Para obtener más información, consulte Manejar las excepciones de servicio Lambda.

Gestión de un fallo mediante Catch

En este ejemplo se utiliza un campo Catch. Cuando una función de Lambda produce un error, se detecta el error y la máquina de estado adopta elfallbackestado.


{
   "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:us-east-1:123456789012:function:FailFunction",
         "Catch": [ {
            "ErrorEquals": ["HandledError"],
            "Next": "fallback"
         } ],
         "End": true
      },
      "fallback": {
         "Type": "Pass",
         "Result": "Hello, AWS Step Functions!",
         "End": true
      }
   }
}

Esta variante utiliza el código de error predefinidoStates.TaskFailed, que coincide con cualquier error que una función de Lambda puede devolver.


{
   "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:us-east-1:123456789012:function:FailFunction",
         "Catch": [ {
            "ErrorEquals": ["States.TaskFailed"],
            "Next": "fallback"
         } ],
      "End": true
      },
      "fallback": {
         "Type": "Pass",
         "Result": "Hello, AWS Step Functions!",
         "End": true
      }
   }
}

Gestión de un tiempo de espera mediante Reintento

Esta máquina de estado utiliza unRetrycampo para reintentarTaskestado que se agota el tiempo de espera según el valor de tiempo de espera especificado enTimeoutSeconds. La invocación de la función Lambda en esteTaskstate se reintenta dos veces con un retroceso exponencial entre los reintentos.


{
   "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:us-east-1:123456789012:function:sleep10",
         "TimeoutSeconds": 2,
         "Retry": [ {
            "ErrorEquals": ["States.Timeout"],
            "IntervalSeconds": 1,
            "MaxAttempts": 2,
            "BackoffRate": 2.0
         } ],
         "End": true
      }
   }
}

Gestión de un tiempo de espera mediante Catch

En este ejemplo se utiliza un campo Catch. Cuando se agota un tiempo de espera, la maquina de estado adopta el estado fallback.


{
   "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:us-east-1:123456789012:function:sleep10",
         "TimeoutSeconds": 2,
         "Catch": [ {
            "ErrorEquals": ["States.Timeout"],
            "Next": "fallback"
         } ],
         "End": true
      },
      "fallback": {
         "Type": "Pass",
         "Result": "Hello, AWS Step Functions!",
         "End": true
      }
   }
}

nota

Puede conservar la entrada del estado y el error utilizando ResultPath. Consulte Uso de ResultPath para incluir el error y la entrada en un Catch.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Tutorial: Examinar las ejecuciones de máquinas de estado

Invocación de Step Functions