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 riprendersi automaticamente dagli 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 dalla macchina 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. Inoltre, include 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 e stabili sull'errore:
- domain: il raggruppamento logico dell'errore, in genere
merchantapi.googleapis.com. - metadata: una mappa di 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 contesto e istruzioni aggiuntivi per risolvere il problema. Questo campo non è presente per tutti gli errori, ma prevediamo di espandere la sua copertura nel tempo per gli errori in cui potrebbe essere necessario un contesto più ampio.
- Altri campi dinamici: altre chiavi che forniscono il 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 è stato formattato in modo errato.
{
"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. Dovresti 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 analizzi o si basi sul contenuto di testo del campomessagefield, in quanto potrebbe cambiare senza preavviso per migliorare la chiarezza o aggiungere contesto.- Valori
details.metadata: sebbene le chiavi siano stabili, i valori delle chiavi informative potrebbero cambiare. Ad esempio, se viene fornita una chiaveHELP_CENTER_LINK, l'URL specifico a cui rimanda 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 la tua integrazione gestisca gli errori in modo corretto.
Utilizzare 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, poiché più errori potrebbero condividere lo stesso codice di stato.
Non analizzare il messaggio di errore
Come indicato nella sezione sulla stabilità, il campo message è destinato al consumo umano.
Se hai bisogno di informazioni dinamiche (ad es. quale campo non è valido), estraile dalla mappa metadata utilizzando chiavi stabili come FIELD_LOCATION, 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 di tempo 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 per minuto per un gruppo di quote specifico. Riduci il tasso di richieste.internal_error: in genere sono temporanei. Riprova con il backoff esponenziale. Nota: seinternal_errorpersiste dopo più tentativi con backoff, consulta Come contattare l'assistenza dell'API Merchant supporto.
Come contattare l'assistenza dell'API Merchant
Se devi contattare l'assistenza dell'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
- I timestamp o l'intervallo di tempo durante il quale è stato chiamato il metodo e sono stati ricevuti gli errori