¿Cómo soluciono los errores 500 cuando uso las integraciones de enlaces de VPC con las API de REST de API Gateway?

Descripción corta

Es posible que API Gateway con integraciones de enlaces de VPC no pueda reenviar el tráfico a los recursos de backend.

También puede devolver un código de estado "HTTP 500" por uno de los siguientes motivos:

• El enlace de VPC tiene el estado Error. O bien, el servicio de punto de enlace no existe o está en estado Rechazado.
• El grupo de destino muestra el objetivo registrado como en mal estado o que no está en uso.
• Los grupos de seguridad no permiten el tráfico en puertos concretos.
• La lista de control de acceso de la red (ACL de la red) bloquea el tráfico.
• El objetivo no escucha en los puertos de destino.
• El certificado del nombre de dominio no coincide con el equilibrador de carga de red o el equilibrador de carga de aplicación activado por TLS.

Si has activado Registros de Amazon CloudWatch para tu API, en los registros de ejecución aparecerá un mensaje de error con la causa del error.

Resolución

Validación de la conectividad de backend

Antes de solucionar los problemas de API Gateway, realiza una de las siguientes acciones:

• Usa herramientas como curl o Postman para enviar una solicitud al nombre DNS del equilibrador de carga de red desde tu VPC. Si la solicitud falla, significa que hay un problema con la configuración del equilibrador de carga de red, el estado del objetivo del backend o la red.
• Usa el analizador de accesibilidad de VPC para validar el flujo de tráfico desde las subredes de enlace de VPC de API Gateway a tus recursos de backend.

Confirmación de la causa del error

Activa el registro de la API de CloudWatch. Además, configura el registro de ejecución.

Nota: Al configurar los ajustes de registro, define el nivel de registro en **Registros de errores e información ** y selecciona Rastreo de datos. Esta configuración te proporciona los registros completos de solicitudes y respuestas.

Para identificar la causa de los errores, revisa los registros de ejecución de las API de REST en CloudWatch. A continuación, soluciona el problema según el mensaje de error que recibas.

Solución del error "There was an internal error while executing your request"

Si recibes el siguiente mensaje de error:

"Error: Execution failed due to configuration error: There was an internal error while executing your request"

Para resolver este problema, comprueba las siguientes configuraciones:

• El equilibrador de carga de enlaces de VPC existe y no se ha eliminado.
• Comprueba si el enlace de VPC tiene el estado Disponible. Si el enlace de VPC tiene el estado Error, deberás crear un nuevo enlace de VPC y asociarlo a tu API.
  Nota: Despliega la API después de modificar la solicitud de integración.
• La conexión de punto de enlace del enlace de VPC asociada al equilibrador de carga de red de destino se encuentra en el estado Disponible.
• Has incluido el ID de cuenta de API Gateway específico de la región de AWS en Permitir entidades principales.
• Una conexión de punto de enlace desde la cuenta de API Gateway en las conexiones de punto de enlace del servicio de punto de enlace se encuentra en estado disponible.
• Si API Gateway hace referencia al ID de VPC con una variable de etapa, comprueba si el ID del enlace de VPC es correcto.
• El equilibrador de carga de enlace de VPC escucha en el puerto HTTP/HTTPS para el que se ha configurado la solicitud. Asegúrate de haber configurado los agentes de escucha para el puerto correcto y de que las ACL de la red no bloqueen la solicitud.
• El grupo de destino acepta la solicitud. Las ACL de la red deben permitir el tráfico de entrada y salida, mientras que los grupos de seguridad deben permitir el tráfico de entrada en el caso de los puertos configurados.
• Si la solicitud devuelve un error de código de estado "HTTP 500", es posible que la conexión reciba el número total de paquetes de restablecimiento (RST) de TCP. El servidor de backend debe estar en ejecución. Además, un servicio debe ejecutarse en el objetivo del backend del puerto de destino. Comprueba si el destino de backend está escuchando en el puerto de destino.
• Has desactivado las reglas de entrada para el tráfico de AWS PrivateLink. La opción Aplicar reglas entrantes en el tráfico de PrivateLink aplica todas las regias de seguridad de entrada y salida al tráfico procedente del enlace de VPC. Si no configuras el grupo de seguridad de modo que permita el tráfico procedente del enlace de VPC, puede que el grupo de seguridad bloquee el tráfico de API Gateway.

Solución del error "Host name 'domain.com.com' does not match the certificate subject provided by the peer"

Si recibes el siguiente mensaje de error:

"Error: Execution failed due to configuration error: Host name 'domain.com.com' does not match the certificate subject provided by the peer (CN=myinstance.com)"

Asegúrate de que el nombre de dominio del punto de enlace coincida con el certificado que devuelve el destino del equilibrador de carga activado por TLS. Los certificados que configures como instancia de destino deben ser de confianza según la lista de proveedores de entidades de certificación admitidas.

Solución del error "PKIX path building failed:...unable to find valid certification path to requested target"

Si recibes el siguiente mensaje de error:

"Error: Execution failed due to configuration error: "PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target"

Este error se produce cuando el servicio de API de REST marca como no válido un certificado que devuelve la integración. API Gateway realizará una validación básica del certificado aunque se haya configurado insecureSkipVerification como true en la propiedad TlsConfig de las integraciones.

API Gateway revisa la siguiente información:

• La fecha de vencimiento del certificado
• El nombre del host
• La presencia de una autoridad de certificación (CA)
  Nota: La integración debe incluir y devolver la cadena de certificados completa para que API Gateway verifique la cadena de confianza y establezca una conexión segura. La cadena completa incluye todos los certificados intermedios, desde el certificado del servidor hasta el certificado de CA raíz. Además, la CA raíz debe incluir keyUsage con keyCertSign y basicConstraints con CA:TRUE. Para obtener más información, consulta el objeto x-amazon-apigateway-integration.tlsConfig object.

Solución del error "Cannot verify ECDH ServerKeyExchange signature"

Si recibes el siguiente mensaje de error:

"Error: Execution failed due to configuration error: Cannot verify ECDH ServerKeyExchange signature"

Este error se produce cuando una clave y el certificado correspondiente no coinciden y se produce un error en el protocolo de enlace TLS. Para solucionar este problema, comprueba el contenido de los archivos que utilizaste para las entidades de certificación, las claves y los certificados configurados.

Solución del error "Execution failed due to an internal error"

Si recibes el siguiente mensaje de error:

"Error: Execution failed due to an internal error"

Este error se produce cuando API Gateway no se conecta al equilibrador de carga a través del enlace de VPC porque el objetivo se restablece en el equilibrador de carga. Para solucionar este problema, establece en el objetivo un tiempo de espera superior al predeterminado en el equilibrador de carga de 350 segundos.

Solución del error "Execution failed due to a VPC link error"

Si recibes el siguiente mensaje de error:

"Error: Execution failed due to a VPC link error"

API Gateway tiene muchas dependencias. Es posible que veas errores cuando una de las dependencias tenga errores de conexión transitorios. En el caso de errores de baja frecuencia, se recomienda implementar reintentos con retroceso exponencial. Si la frecuencia de los errores es alta, ponte en contacto con AWS Support. Asegúrate de proporcionar los registros de ejecución de API Gateway que muestran los errores.

Solución del error "Execution failed due to configuration error: Not a valid protocol version"

Si recibes el siguiente mensaje de error:

"Error: Execution failed due to configuration error: Not a valid protocol version"

Este error se produce si la integración respondió con una respuesta HTTP que no es válida e incumple la especificación HTTP. El backend integrado puede enviar datos que no son válidos a API Gateway.

Para solucionar este problema, toma estas medidas:

• Reproduce la solicitud que realizaste desde Amazon API Gateway. Para probar el punto de enlace de servicio que utiliza Amazon API Gateway, crea un punto de enlace de VPC que esté vinculado al ID del punto de enlace de servicio. También puedes ejecutar capturas de paquetes para revisar la respuesta devuelta por el backend integrado.
• Para evitar el cifrado duplicado, cambia el protocolo del equilibrador de carga a TLS o TCP, según la respuesta de los objetivos.
• Asegúrate de que insecureSkipVerification se haya definido como true en la propiedad TlsConfig de las integraciones.

Supervisión y detección de errores y problemas

Utiliza las siguientes herramientas para determinar si el problema es transitorio o si hay problemas de configuración persistentes:

• Supervisa las métricas 5XXError y IntegrationLatency de API Gateway en CloudWatch para detectar patrones.
• Activa el rastreo de AWS X-Ray para supervisar las rutas de solicitud de API Gateway al enlace de VPC, del enlace de VPC al equilibrador de carga de red y del equilibrador de carga de red al backend.

Información relacionada

Understanding VPC Links in Amazon API Gateway private Integrations (Descripción de los enlaces de VPC en integraciones privadas de Amazon API Gateway)

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

Configuración de un equilibrador de carga de red para integraciones privadas de API Gateway