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

Descripción breve

Los códigos de respuesta HTTP 5xx indican errores del servidor. Entre los errores 5xx de API Gateway se incluyen los casos siguientes:

• 500: servidor interno
• 502: puerta de enlace incorrecta
• 503: servicio no disponible
• 504: se ha agotado el tiempo de espera de la solicitud de punto de conexión

Solución

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

Utilice los registros de CloudWatch para encontrar errores 5xx en API Gateway. La métrica 5XXError de API Gateway cuenta la cantidad de errores del servidor que se registran en un período determinado.

Nota: Si recibe errores al ejecutar los comandos de la interfaz de la línea de comandos de AWS (AWS CLI), asegúrese de utilizar la versión más reciente de la AWS CLI.

Error 500: error de servidor interno

Este error puede producirse debido a cualquiera de los siguientes escenarios:

• Errores en el código de la función de AWS Lambda
• Faltan permisos para usar una variable de etapa
• Falta la asignación de códigos de estado HTTP o es incorrecta
• Problemas de limitación
• Método HTTP POST no definido
• Permisos de Lambda
• Problema con el formato JSON de la función de Lambda
• El tamaño de carga del backend supera los 10 MB
• Integración de puntos de conexión privados
• Errores de servicio internos

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

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

Faltan permisos para usar 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 error, consulte I defined my Lambda integration in API Gateway using a stage variable. Why do I get an "Internal server error" and a 500 status code when I invoke the API method? (He definido mi integración de Lambda en API Gateway con 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

Los errores 500 también pueden aparecer si falta la asignación del código de estado HTTP o si dicha asignación es incorrecta. Para resolver este problema, configure integraciones simuladas en API Gateway.

Problemas de limitación

Si un gran número de solicitudes está saturando 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 el límite de cuota de API Gateway. Si supera el límite de cuota de servicio, puede solicitar un aumento de cuota.

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

A continuación, utilice el comando de AWS CLI create-deployment para implementar la API de REST:

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

Permisos de Lambda

Asegúrese de que la política basada en recursos de la función de Lambda integrada o del autorizador 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 de Lambda.

Problema con el formato JSON de la función de Lambda

La función de Lambda integrada no devuelve resultados de acuerdo con el formato JSON predefinido para las API de REST y HTTP. Actualice la función de Lambda o el autorizador de Lambda en formato JSON:

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 carga del backend supera los 10 MB

El tamaño máximo de carga del backend es de 10 MB. No puede aumentar el tamaño. Asegúrese de que el tamaño de carga del backend no supere 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.

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 502: puerta de enlace incorrecta

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

Para solucionar este problema, 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 de proxy de Lambda?).

**Nota:**Cuando API Gateway interpreta 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 503: servicio no disponible

Hay un código de error 503 relacionado con la integración del backend y con si la API de API Gateway no puede recibir una respuesta.

Este error puede producirse en los siguientes escenarios:

• El servidor de backend está sobrecargado más allá de su capacidad y no puede procesar nuevas solicitudes de clientes.
• El servidor de backend se encuentra en mantenimiento temporal.

Para resolver este error, considere la posibilidad de aprovisionar más recursos en el servidor de backend y activar un mecanismo de retroceso exponencial y reintento en el cliente. A continuación, realice la solicitud de nuevo.

Error 504: se ha agotado el tiempo de espera de la solicitud de punto de conexión

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 error, consulte ¿Cómo soluciono 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