¿Cómo puedo solucionar los problemas de errores de invocación HTTP de API Gateway?

Resolución

Para solucionar los errores 5xx de las API de REST que ha configurado para registrar las solicitudes de recursos y operaciones, utilice el runbook AWSSupport-TroubleshootAPIGatewayHttpErrors. 

O bien, puede solucionar manualmente los errores 5xx.

Nota: Si se muestran errores al ejecutar comandos de la Interfaz de la línea de comandos de AWS (AWS CLI), consulte Solución de problemas de AWS CLI. Además, asegúrese de utilizar la versión más reciente de la AWS CLI.

Uso del runbook automatizado para solucionar errores

Antes de que el runbook AWSSupport-TroubleshootAPIGatewayHttpErrors analice los registros de Amazon CloudWatch, el runbook valida la API, el recurso, la operación y la etapa.

Concesión de los permisos necesarios

Antes de ejecutar el runbook, asegúrese de que su usuario o rol de AWS Identity and Access Management (IAM) tenga los permisos correctos. Compruebe que su usuario o rol de IAM tenga permiso para acceder al runbook. 

Además, el usuario de IAM o el rol de servicio asumido que ejecuta la automatización debe tener los siguientes permisos:

• apigateway:GET
• logs:GetQueryResults
• logs:StartQuery
• ssm:DescribeAutomationExecutions
• ssm:GetAutomationExecution
• ssm:DescribeAutomationStepExecutions
• ssm:StartAutomationExecution
• ssm:DescribeDocument
• ssm:GetDocument
• ssm:ListDocuments

Ejecución de la automatización

Siga estos pasos:

1. Abra el runbook AWSSupport-TroubleshootAPIGatewayHttpErrors.
2. Seleccione Ejecutar automatización.
   Para los parámetros de entrada, introduzca lo siguiente:
   RestApiId: El ID de la API que está solucionando.
   StageName: El nombre de la etapa implementada.
   ResourcePath: La ruta de recursos de la operación.
   HttpMethod: El método para la ruta de recursos configurada.
   StartTime: La fecha y la hora de inicio para consultar los registros de CloudWatch. El formato debe ser aaaa-MM-ddTHH:mm:ss y la zona horaria debe ser UTC.
   EndTime: La fecha y la hora de finalización para detener la consulta de los registros de CloudWatch. El formato debe ser aaaa-MM-ddTHH:mm:ss y la zona horaria debe ser UTC.
   AccessLogs: Los registros de acceso que desea que analice el runbook.
   ExecutionId: El ID de ejecución de la solicitud en la que se producen errores.
   AutomationAssumeRole: El ARN del rol de IAM que permite a Automatización realizar las acciones en su nombre. Si no especifica un rol, la automatización usa los permisos del usuario que inicia el runbook.
   StageName: El nombre de la etapa implementada.
3. Seleccione Ejecutar.
4. Revise la sección Resultados para ver los resultados detallados.
   Nota: La automatización se completa correctamente, incluso cuando el runbook no encuentra registros.

Solución manual de los errores de código de estado 5xx

Nota: La siguiente resolución se aplica solo a las API de REST.

Antes de empezar, active Registros de Amazon CloudWatch para solucionar los errores de API Gateway. Para encontrar errores 5xx en sus registros de ejecución, consulte ¿Cómo puedo encontrar errores de API de REST de puerta de enlace en mis registros de CloudWatch? La métrica 5XXError de API Gateway captura la cantidad de errores en el servidor en un periodo específico.

Errores en el código de la función de Lambda

Para ver los errores 500 del punto de enlace de la API que se integran con AWS Lambda, consulte Patrones de gestión de errores en Amazon API Gateway y AWS Lambda.

Faltan permisos para una variable de etapa

Si utiliza una variable de etapa para configurar API Gateway para que invoque una función de Lambda, es posible que reciba un error de servidor interno. Para resolver este problema, consulte He definido mi integración de Lambda en API Gateway mediante una variable de etapa. ¿Por qué aparece un «error de servidor interno» y un código de estado 500 cuando invoco el método de la API?

Falta la asignación de códigos de estado HTTP o es incorrecta

Para resolver este problema, configure integraciones simuladas en API Gateway.

Problemas de limitación

Si un gran número de solicitudes limita el servicio de backend, es posible que la API de API Gateway devuelva un error de servidor interno. Para resolver este problema, active un mecanismo de retroceso exponencial y reintento y, a continuación, realice la solicitud de nuevo. Si el problema persiste, compruebe la cuota de API Gateway. Si supera la cuota de servicio, puede solicitar un aumento de cuota de servicio.

Método HTTP POST no definido

Para la integración con Lambda, debe utilizar el método HTTP de POST para la solicitud de integración. Ejecute el siguiente comando de AWS CLI put-integration para actualizar la solicitud de integración de método:

aws apigateway put-integration \
    --rest-api-id id \
   --resource-id id \
    --http-method ANY \
    --type AWS_PROXY \
    --integration-http-method POST \
    --uri arn:aws:apigateway:us-east-2:lambda:path//2015-03-31/functions/arn:aws:lambda:us-east-2:account_id:function:helloworld/invocations

Nota: Sustituya rest-api-id por su ID de API de REST, resource-id por su ID de recurso y el URI de ejemplo por su URI.

A continuación, ejecute el siguiente comando create-deployment de la AWS CLI para desplegar la API de REST:

aws apigateway create-deployment \
    --rest-api-id id \
    --stage-name stage-resource

Nota: Sustituya rest-api-id por su ID de API de REST y stage-resource por su recurso de etapa para crear el recurso de despliegue.

Permisos de Lambda

Asegúrese de que la política basada en recursos de la función de Lambda o del autorizador de Lambda incluya permisos para que la API invoque la función. 

Problema de formato JSON de salida de la función Lambda

Si el resultado de la función Lambda integrada no se ajusta al formato JSON especificado para las API de REST, se mostrará un error. Asegúrese de usar el formato JSON correcto para la salida de las funciones de Lambda para integraciones de proxy y de los autorizadores de Lambda. Usa los siguientes formatos JSON de ejemplo.

Ejemplo de función de Lambda para la integración de proxy:

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headerName": "headerValue", ... },
    "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
    "body": "..."
}

Ejemplo de autorizador de Lambda:

{
   "principalId": "user",
  "policyDocument": {
    "Version": "2012-10-17",
    "Statement": [
      { "Action": "execute-api:Invoke",
        "Effect": "Deny",
        "Resource": "arn:aws:execute-api:us-west-2:123456789012:ymy8tbxw7b/dev/GET/"
      }
    ]
  }
}

El tamaño de carga útil del backend supera los 10 MB

La cuota máxima de API HTTP para un tamaño de carga útil de backend es de 10 MB. No puede aumentar el tamaño, así que asegúrese de que el tamaño de la carga útil del backend no supere la cuota de 10 MB.

Integración de puntos de enlace privados

Si utiliza un punto de enlace de API privado, también debe configurar la integración privada de API Gateway.

Errores de servicio internos

Si AWS tiene problemas con el servicio interno, es posible que reciba un error 500. Espere a que el problema se resuelva en AWS o en el servicio de API Gateway y, a continuación, realice la solicitud de nuevo con un retroceso exponencial.

Error de código de estado 502: puerta de enlace incorrecta

Cuando API Gateway no puede procesar la respuesta como puerta de enlace o proxy, recibirá un código de estado 502 de puerta de enlace incorrecta. Para solucionar este problema, consulte ¿Cómo se resuelven los errores HTTP 502 de las API de REST de API Gateway con la integración de proxy de Lambda?

Nota: Cuando API Gateway lee la respuesta del servicio de backend, utiliza plantillas de asignación para asignar el formato en la sección de respuestas de integración. Para obtener más información, consulte Configuración de una respuesta de integración en API Gateway.

Error de código de estado 503: servicio no disponible

Se produce un error en el código de estado 503 porque la integración del backend no está disponible, por lo que la API de API Gateway no recibe respuesta.

Este error puede producirse por los siguientes motivos:

• El servidor de backend superó su capacidad y no puede procesar las solicitudes de nuevos clientes.
• El servidor de backend está completando el mantenimiento temporal.

Para resolver este problema, puede agregar más recursos al servidor de backend y activar un mecanismo de retroceso exponencial y reintento en el cliente. A continuación, realice la solicitud de nuevo.

Error de código de estado 504: se ha agotado el tiempo de espera de la solicitud de punto de enlace

Si una solicitud de integración tarda más que el parámetro de tiempo de espera de integración máximo de la API de REST de API Gateway, esta última devuelve un código de estado HTTP 504. Para resolver este problema, consulte ¿Cómo soluciono los errores de tiempo de espera HTTP 504 de la API con API Gateway?

Información relacionada

Flujos de trabajo de automatización de AWS Support (SAW)

Prácticas recomendadas sobre seguridad para Amazon API Gateway

Supervisión de la ejecución de la API de REST con métricas de Amazon CloudWatch

¿Cómo puedo activar los registros de CloudWatch para solucionar problemas con mi API de REST o API de WebSocket de API Gateway?