¿Cómo puedo usar los registros de API Gateway para solucionar problemas de API?

Descripción corta

Para solucionar los problemas con una API de REST o una API de WebSocket de API Gateway, usa Registros de Amazon CloudWatch para acceder a tus registros. Asegúrate de adjuntar todos los permisos necesarios al rol de AWS Identity and Access Management (IAM) de API Gateway. Para obtener instrucciones, consulta ¿Cómo puedo activar los registros de CloudWatch para solucionar problemas con mi API de REST o API de WebSocket de API Gateway?

Nota: Las API HTTP solo admiten el registro de acceso. Para más información sobre cómo configurar el registro para estas API, consulta Configuración del registro de API HTTP en API Gateway.

Resolución

Tras activar el registro, API Gateway crea automáticamente un grupo de registros de CloudWatch denominado API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}. Usa este grupo para seguir solucionando los problemas que surjan. Para más información, consulta Formatos de registro de CloudWatch para API Gateway.

Comprobación de errores de autorización

Si activas los autorizadores de AWS Lambda para tu API, los registros indican si la solicitud está autorizada e incluyen los ID del autorizador y de la solicitud.

Registros autorizados de ejemplo:

Starting authorizer: 62mgrc for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0
Successfully completed authorizer execution

Registros no autorizados de ejemplo:

Starting authorizer: 62mgrc for request: fd443056-60d0-425f-874e-e93e5d61351e  
Unauthorized request: fd443056-60d0-425f-874e-e93e5d61351e

Para más información, consulta ¿Por qué aparecen errores "401 Unauthorized" de API Gateway después de crear un autorizador de Lambda?

Actualización de la configuración del plan de uso

Tras los registros del autorizador de Lambda, API Gateway verifica el plan de uso de la solicitud de API. Si no has configurado un plan de uso, las solicitudes de API no se tienen en cuenta para la limitación.

Registros de planes de uso de ejemplo:

Verifying Usage Plan for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0. API Key: API Stage: <api_id>/<stage>
API Key authorized because method 'GET /' does not require API Key. Request will not contribute to throttle or quota limits
Usage Plan check succeeded for API Key and API Stage <api_id>/<stage>

Si configuras las API con claves de API y falta el encabezado X-API-Key, los registros muestran un error similar al siguiente mensaje:

"API Key not authorized because method 'GET /' requires API Key and API Key is not associated with a Usage Plan for API Stage <api_id>/<stage>: API Key was required but not present"

Para resolver este problema, revisa la configuración de la API. Debes asociar la clave de API al plan de uso requerido e incluir la clave en la solicitud como encabezado X-API-KEY con el valor correcto.

Si agregas la clave de API correcta en el encabezado y API Gateway limita la solicitud, los registros muestran un error similar al siguiente:

"API Key **FGQes7 exceeded throttle limit for API Stage <api_id>/<stage>: Key throttle limit exceeded for Usage Plan ID iwuzkt. Limit: 5.00 Burst: 0
Method completed with status: 429"

Para resolver este problema, completa los pasos de la sección ¿Cómo puedo solucionar los errores "429 Too Many Requests" o "Limit Exceeded" en mi API con API Gateway?

Tipos de registro de solicitudes

Cuando activas el rastreo de datos y los registros de errores e información, los registros de API Gateway contienen más detalles para ayudarte a solucionar problemas. Para saber dónde está el error de la solicitud de API Gateway, revisa los siguientes tipos de registro para obtener más información.

Nota: En los registros de solicitudes, debes elegir Registros de errores e información en el menú desplegable de registros de CloudWatch. A continuación, activa el seguimiento de datos para los registros de ejecución. Se recomienda no activar el seguimiento de datos para las API de producción, ya que podrías registrar datos confidenciales.

Registros de solicitudes de métodos

Los registros de solicitudes de métodos incluyen información detallada que recibe una solicitud de API, incluida la ruta de la solicitud, el parámetro de la consulta, el encabezado de la solicitud y el cuerpo de la solicitud.

Registro de ejemplo de solicitudes de métodos:

(####) Method request path: {...}
(####) Method request query string: {...}
(####) Method request headers: {User-Agent=...}
(####) Method request body before transformations: ...

Registros de solicitudes de puntos de enlace

Los registros de solicitudes de puntos de enlace incluyen información detallada que recibe una solicitud de API, como el URI, los encabezados de la solicitud y el cuerpo de la solicitud.

Registro de ejemplo de solicitudes de puntos de enlace:

(####) Endpoint request URI: ...
(####) Endpoint request headers: {...}
(####) Endpoint request body after transformations: {...}

Los datos incluidos en las solicitudes de puntos de enlace se envían a tu integración de backend para su posterior procesamiento.

Registros de respuesta de puntos de enlace

Los registros de respuesta de puntos de enlace incluyen los datos que devuelven las integraciones de backend, incluidos el código de estado, los encabezados, el cuerpo y la latencia de integración.

Registro de ejemplo de respuestas de puntos de enlace:

(####) Received response. Status: YYY, Integration latency: ZZZ ms
(####) Endpoint response headers: {...}
(####) Endpoint response body before transformations: {...}

Registros de respuestas de métodos

Los registros de respuestas de métodos incluyen los encabezados y el cuerpo que se envían al cliente después de la transformación.

Registro de ejemplo de respuestas de métodos:

(####) Method response body after transformations: ...
(####) Method response headers: {...}

Importante: API Gateway limita los eventos de registro a 1024 bytes. API Gateway trunca los eventos de registro de más de 1024 bytes, como los cuerpos de solicitud y respuesta, antes de enviarlos a los registros de CloudWatch.

Información relacionada

¿Cómo puedo solucionar los problemas que faltan en los registros de CloudWatch para las API de REST de API Gateway?

Configuración del registro de CloudWatch para las API de REST en API Gateway

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

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

Solución de problemas de Amazon API Gateway con variables de observabilidad mejoradas