¿Cómo puedo solucionar los errores 5xx de API Gateway?

Descripción corta

Los códigos de respuesta HTTP 5xx indican errores del servidor. Los errores 5xx de API Gateway incluyen:

• 500 internal server (error interno del servidor)
• 502 bad gateway (puerta de enlace no válida)
• 503 service unavailable (servicio no disponible)
• 504 endpoint request timed out (tiempo de espera de solicitud de punto de conexión agotado)

Resolución

Antes de comenzar, siga los pasos para activar los registros de Amazon CloudWatch para solucionar los errores de API Gateway.

Puede utilizar los registros de Amazon CloudWatch para encontrar errores 5xx de API Gateway. La métrica 5XXError de API Gateway cuenta el número de errores del lado del servidor registrados en un período determinado.

Nota: Si se producen errores al ejecutar comandos de la Interfaz de la línea de comandos de AWS (AWS CLI), asegúrese de que utiliza la versión más reciente de la AWS CLI.

500 error: internal server error (error interno del servidor)

Este error se puede deber a:

• Errores en el código de la función AWS Lambda.
• Falta de permisos para utilizar una variable de fase.
• Asignación de código de estado HTTP incorrecta o ausente.
• Problemas de limitación.
• El método HTTP de POST no está definido.
• Permisos Lambda.
• Problema de formato JSON de la función Lambda.
• El tamaño de la carga útil del backend supera los 10 MB.
• Integración del punto de conexión privado.

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

Los errores 500 de los puntos de conexión de la API que se integran con Lambda podrían indicar que la función Lambda tiene un error en el código. Para obtener más información y solucionar problemas, consulte Error handling patterns in Amazon API Gateway and AWS Lambda (Patrones de gestión de errores en Amazon API Gateway y AWS Lambda).

Falta de permisos para utilizar una variable de fase

Si configura una puerta de enlace de API para invocar una función de AWS Lambda utilizando una variable de fase, es posible que reciba un “internal server error” (error interno del servidor). Para resolver este error, consulte ¿Por qué aparece el error “Internal server error” (Error interno del servidor) y un código de estado 500 al invocar el método de API?

Asignación de código de estado HTTP incorrecta o ausente

La asignación de códigos de estado HTTP incorrectos o ausentes también puede dar lugar a errores 500. Para resolver este error, puede configurar integraciones simuladas en API Gateway.

Problemas de limitación

Si el servicio de backend está limitado debido a un gran número de solicitudes, es posible que la API Gateway devuelva un “Internal server error” (Error interno del servidor). Puede activar un mecanismo de retroceso exponencial y reintento e intentar la solicitud de nuevo. Si el problema persiste, comprueba el límite de cuota de la API Gateway. Si ha superado el límite de la cuota de servicio, puede solicitar un aumento de la cuota.

El método HTTP de POST no está definido

En la integración de Lambda, debe utilizar el método HTTP de POST para la solicitud de integración.

Actualice la solicitud de integración de métodos utilizando el comando put-integration de la CLI de AWS de esta manera:

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

A continuación, despliegue la API de REST utilizando el comando create-deployment de la CLI de AWS de esta manera:

aws apigateway create-deployment \
    --rest-api-id id \
    --stage-name <value>

Permisos de Lambda

Asegúrese de que la función Lambda integrada o la política basada en recursos de los autorizadores de Lambda incluya permisos para que la API invoque la función. Siga las instrucciones para actualizar la política basada en recursos de la función Lambda.

Problema con el formato JSON de la función Lambda

La función Lambda integrada no devuelve la salida de acuerdo con el formato JSON predefinido para las API de REST y las API HTTP. Actualice su función Lambda o el formato JASON de la función Lambda del autorizador de esta manera:

API de REST

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

API HTTP

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headername": "headervalue", ... },
    "multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... },
    "body": "..."
}

El tamaño de la carga útil del backend ha superado los 10 MB

El tamaño máximo de la carga útil del backend es de 10 MB y no se puede aumentar. Asegúrese de que el tamaño de la carga útil del backend no supera la cuota predeterminada de 10 MB.

Integración de puntos de conexión privados

Si utiliza un punto de conexión de API privado, también debe configurar la integración privada de API Gateway. Siga las instrucciones para configurar las integraciones privadas de API Gateway.

502 error: bad gateway (Error 502: puerta de enlace no válida)

Un código de error 502 está relacionado con el servicio de AWS con el que se integra la API Gateway, como una función de AWS Lambda. API Gateway no ha podido procesar la respuesta como puerta de enlace o proxy.

Para solucionar el error 502 al integrarse con una función de proxy Lambda, consulte How do I resolve HTTP 502 errors from API Gateway REST APIs with Lambda proxy integration? (¿Cómo se resuelven los errores HTTP 502 de las API de REST de API Gateway con la integración del proxy Lambda?).

Nota: API Gateway interpreta la respuesta del servicio de backend en un formato que se puede asignar en la sección de respuestas de integración mediante plantillas de asignación. Para obtener más información, consulte Configuración de una respuesta de integración en API Gateway.

Error 503: service unavailable (servicio no disponible)

Un código de error 503 está relacionado con la integración del backend y la API de API Gateway no puede recibir una respuesta.

Este error puede ocurrir si el servidor backend se encuentra:

• Sobrecargado por encima de su capacidad y no puede procesar las solicitudes de nuevos clientes.
• El servidor backend se encuentra en mantenimiento temporal.

Para resolver este error, considera aprovisionar más recursos al servidor backend y activar un retroceso exponencial y reintento en el cliente. A continuación, vuelva a intentar la solicitud.

Error 504: endpoint request timed out (tiempo de espera de solicitud de punto de conexión agotado)

Si una solicitud de integración tarda más que el parámetro de tiempo máximo de integración de la API de REST de API Gateway, API Gateway devuelve un código de estado HTTP 504.

Para resolver este error, consulte ¿Cómo se solucionan los errores de tiempo de espera HTTP 504 de la API con API Gateway?

---

Información relacionada

Prácticas recomendadas sobre seguridad para Amazon API Gateway

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