Questa guida spiega come gestire gli errori restituiti dall'API Merchant. Comprendere la struttura e la stabilità della risposta di errore è fondamentale per creare integrazioni robuste in grado di ripristinare automaticamente gli errori o fornire feedback significativi agli utenti.
Panoramica
Quando una richiesta dell'API Merchant non va a buon fine, l'API restituisce un codice di stato HTTP standard
(4xx o 5xx) e un corpo della risposta JSON contenente i dettagli dell'errore.
L'API Merchant segue lo standard AIP-193 per i dettagli degli errori, fornendo informazioni leggibili automaticamente che consentono alla tua applicazione di gestire scenari di errore specifici in modo programmatico.
Struttura della risposta di errore
La risposta di errore è un oggetto JSON che contiene campi standard come code,
message e status. Fondamentalmente, include anche un array details. Per
gestire gli errori in modo programmatico, devi cercare un oggetto all'interno di details
in cui @type è type.googleapis.com/google.rpc.ErrorInfo.
Questo oggetto ErrorInfo fornisce dati strutturati stabili sull'errore:
- domain: il raggruppamento logico dell'errore, in genere
merchantapi.googleapis.com. - metadati: una mappa dei valori dinamici correlati all'errore. Ad esempio:
- REASON: un identificatore specifico e stabile per l'errore esatto (ad es.
INVALID_NAME_PART_NOT_NUMBER,PERMISSION_DENIED_ACCOUNTS). Questo campo è sempre presente. Utilizza questo campo per la gestione degli errori granulare nella logica dell'applicazione. - HELP_CENTER_LINK: fornisce ulteriore contesto e istruzioni per risolvere il problema. Questo campo non è presente per tutti gli errori, ma prevediamo di ampliare la sua copertura nel tempo per gli errori in cui potrebbe essere necessario più contesto.
- Altri campi dinamici: altre chiavi che forniscono contesto, ad esempio il nome
del campo non valido (
FIELD_LOCATION) o il valore che ha causato l'errore (FIELD_VALUE).
- REASON: un identificatore specifico e stabile per l'errore esatto (ad es.
Esempi di risposte di errore
Il seguente JSON mostra la struttura di un errore dell'API Merchant in cui il nome di una risorsa non è valido.
{
"error": {
"code": 400,
"message": "[name] The part `account` of the resource name in field `name` must be a number, but has value: `abcd`.",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "invalid",
"domain": "merchantapi.googleapis.com",
"metadata": {
"VARIABLE_NAME": "account",
"FIELD_LOCATION": "name",
"FIELD_VALUE": "abcd",
"REASON": "INVALID_NAME_PART_NOT_NUMBER"
}
}
]
}
}
Ecco un esempio di errore di autenticazione:
{
"error": {
"code": 401,
"message": "The caller does not have access to the accounts: [1234567]",
"status": "UNAUTHENTICATED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "unauthorized",
"domain": "merchantapi.googleapis.com",
"metadata": {
"ACCOUNT_IDS": "[1234567]",
"REASON": "PERMISSION_DENIED_ACCOUNTS"
}
}
]
}
}
Stabilità dei campi di errore
Quando scrivi la logica di gestione degli errori, è importante sapere su quali campi è sicuro fare affidamento e quali potrebbero cambiare.
- Campi stabili:
details.metadata.REASON: l'identificatore di errore specifico. Devi fare affidamento su questo campo per la logica del flusso di controllo della tua applicazione.- Chiavi
details.metadata: le chiavi all'interno della mappa dei metadati (ad es.FIELD_LOCATION,ACCOUNT_IDS) sono stabili. code: il codice di stato HTTP di alto livello (ad es.400,401,503) è stabile.
- Chiavi
Campi instabili:
message: il messaggio di errore leggibile non è stabile. È destinato solo al debug degli sviluppatori. Non scrivere codice che analizza o si basa sul contenuto di testo del campomessage, in quanto potrebbe cambiare senza preavviso per migliorare la chiarezza o aggiungere contesto.- Valori
details.metadata: mentre le chiavi sono stabili, i valori per le chiavi informative potrebbero cambiare. Ad esempio, se viene fornita una chiaveHELP_CENTER_LINK, l'URL specifico a cui punta potrebbe essere aggiornato a una pagina di documentazione più recente senza preavviso. Tuttavia, come accennato in precedenza, il valore didetails.metadata.REASONè stabile.
Best practice
Segui queste best practice per assicurarti che l'integrazione gestisca gli errori in modo appropriato.
Utilizza details.metadata.REASON per la logica
Utilizza sempre il REASON specifico all'interno della mappa metadata per determinare la
causa di un errore. Non fare affidamento solo sul codice di stato HTTP, in quanto più errori
potrebbero condividere lo stesso codice di stato.
Non analizzare il messaggio di errore
Come indicato nella sezione Stabilità, il campo message è destinato al consumo umano.
Se hai bisogno di informazioni dinamiche (ad esempio quale campo non è valido), estraile dalla mappa metadata utilizzando chiavi stabili come FIELD_LOCATION e VARIABLE_NAME.
Implementare il backoff esponenziale
Per gli errori che indicano una mancata disponibilità temporanea o una limitazione della frequenza, implementa una strategia di backoff esponenziale. Ciò significa attendere un breve periodo prima di riprovare e aumentare il tempo di attesa a ogni errore successivo.
quota/request_rate_too_high: questo errore indica che hai superato la quota minuto per un gruppo di quote specifico. Riduci la frequenza delle richieste.internal_error: di solito sono temporanei. Riprova con backoff esponenziale. Nota:seinternal_errorpersiste dopo diversi tentativi con backoff, consulta Come contattare l'assistenza dell'API Merchant.
Come contattare l'assistenza API Merchant
Se devi contattare l'assistenza API Merchant in merito a un errore specifico, fornisci le seguenti informazioni nella richiesta:
- La risposta di errore esatta ricevuta
- Il nome del metodo API
- Il payload della richiesta
- Timestamp o intervallo di tempo durante il quale è stato chiamato il metodo e sono stati ricevuti errori