Come posso risolvere gli errori 5xx per API Gateway?

Breve descrizione

I codici di risposta HTTP 5xx indicano errori del server. Gli errori di API Gateway 5xx includono i seguenti casi:

• 500 server interni
• 502 gateway errato
• 503 servizio non disponibile
• Richiesta di endpoint 504 scaduta

Risoluzione

Prima di iniziare, segui i passaggi per attivare Amazon CloudWatch Logs per la risoluzione degli errori di API Gateway.

Usa i log di CloudWatch per trovare 5xx errori da API Gateway. La metrica API Gateway 5XXError conta il numero di errori lato server che vengono acquisiti in un determinato periodo.

Nota: Se ricevi errori durante l'esecuzione dei comandi AWS Command Line Interface (AWS CLI), assicurati di utilizzare la versione più recente dell'interfaccia a riga di comando di AWS.

errore 500: errore interno del server

Questo errore può verificarsi a causa di uno dei seguenti scenari:

• Errori nel codice della funzione AWS Lambda
• Autorizzazioni mancanti per l'utilizzo di una variabile di stage
• Mappatura del codice di stato HTTP errata o mancante
• Problemi di limitazione
• Metodo HTTP non definito di POST
• Autorizzazioni Lambda
• Problema di formato JSON della funzione Lambda
• Dimensione del payload del backend superiore a 10 MB
• Integrazione di endpoint privati
• Guasti interni del servizio

Errori nel codice della funzione Lambda

Gli errori dell'endpoint API 500 che si integrano con Lambda potrebbero indicare che la funzione Lambda presenta un errore nel codice. Per ulteriori informazioni e risoluzione dei problemi, consulta Modelli di gestione degli errori in Amazon API Gateway e AWS Lambda.

Autorizzazioni mancanti per l'utilizzo di una variabile di stage

Se utilizzi una variabile stage per configurare un gateway API per richiamare una funzione Lambda, potresti ricevere un errore interno del server. Per risolvere questo errore, vedi Ho definito la mia integrazione Lambda in API Gateway utilizzando una variabile di fase. Perché ricevo un “Errore interno del server” e un codice di stato 500 quando richiamo il metodo API?

Mappatura del codice di stato HTTP errata o mancante

Anche una mappatura del codice di stato HTTP errata o mancante può causare 500 errori. Per risolvere questo problema, configura integrazioni fittizie in API Gateway.

Problemi di limitazione

Se un numero elevato di richieste limita il servizio di backend, l'API API Gateway potrebbe restituire un Errore interno del server. Per risolvere questo problema, attiva un meccanismo di backoff esponenziale e riprova, quindi riprova a eseguire la richiesta. Se il problema persiste, controlla il limite di quota di API Gateway. Se superi il limite di quota del servizio, puoi richiedere un aumento della quota.

Metodo HTTP non definito di POST

Per l'integrazione con Lambda, è necessario utilizzare il metodo HTTP di POST per la richiesta di integrazione.

Esegui il comando put-integration dell'interfaccia a riga di comando di AWS per aggiornare la richiesta di integrazione del metodo:

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

Quindi, utilizza il comando AWS CLI create-deployment per distribuire l'API REST:

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

Autorizzazioni Lambda

Assicurati che la politica basata sulle risorse della funzione Lambda integrata o dell'autorizzatore Lambda includa le autorizzazioni affinché la tua API possa richiamare la funzione. Segui le istruzioni per aggiornare la politica basata sulle risorse della tua funzione Lambda.

Problema di formato JSON della funzione Lambda

La funzione Lambda integrata non restituisce l'output in base al formato JSON predefinito per le API REST e le API HTTP. Aggiorna la tua funzione Lambda o l'autorizzatore Lambda in formato JSON:

REST API:

{
    "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": "..."
}

Dimensione del payload del backend superiore a 10 MB

La dimensione massima del payload del backend è 10 MB. Non puoi aumentare le dimensioni. Assicurati che la dimensione del payload del backend non superi la quota predefinita di 10 MB.

Integrazione di endpoint privati

Se utilizzi un endpoint API privato, devi anche configurare l'integrazione privata di API Gateway. Segui le istruzioni per configurare le integrazioni private di API Gateway.

Guasti interni del servizio

Se AWS presenta problemi di servizio interni, potresti ricevere un errore 500. Attendi che il problema si risolva all'interno di AWS o del servizio API Gateway, quindi riprova la richiesta con un backoff esponenziale.

Errore 502: gateway errato

Un codice di errore 502 è correlato al servizio AWS con cui il tuo API Gateway si integra, ad esempio una funzione AWS Lambda. API Gateway non è in grado di elaborare la risposta come gateway o proxy.

Per risolvere questo problema, vedi Come posso risolvere gli errori HTTP 502 delle API REST di API Gateway con l'integrazione del proxy Lambda?

Nota: Quando API Gateway interpreta la risposta dal servizio di backend, utilizza modelli di mappatura per mappare il formato nella sezione della risposta all'integrazione. Per ulteriori informazioni, consulta Configurare una risposta di integrazione in API Gateway.

Errore 503: servizio non disponibile

Un codice di errore 503 è correlato all'integrazione del backend e se l'API API Gateway non riesce a ricevere una risposta.

Questo errore può verificarsi nei seguenti scenari:

• Il server backend è sovraccarico oltre la sua capacità e non è in grado di elaborare nuove richieste dei client.
• Il server di backend è in manutenzione temporanea.

Per risolvere questo errore, valuta la possibilità di fornire più risorse al server backend e di attivare un meccanismo esponenziale di backoff e riprova sul client. Quindi, riprova la richiesta.

Errore 504: richiesta dell'endpoint scaduta

Se una richiesta di integrazione richiede più tempo del parametro di timeout massimo di integrazione dell'API Gateway REST API, API Gateway restituisce un codice di stato HTTP 504.

Per risolvere questo errore, vedi Come posso risolvere gli errori di timeout dell'API HTTP 504 con API Gateway?

Informazioni correlate

Le migliori pratiche di sicurezza in Amazon API Gateway

Monitoraggio dell'esecuzione delle API REST con i parametri di Amazon CloudWatch