Codici di errore

Questa pagina illustra i codici di errore canonici che devi restituire nelle risposte dell'API quando esegui l'integrazione con Google utilizzando Universal Commerce Protocol (UCP). I codici di errore coerenti garantiscono una comunicazione chiara e aiutano Google a gestire correttamente i diversi scenari.

Quando si verifica un errore aziendale, l'API deve restituire un messaggio di risposta che includa il code appropriato dalla tabella. Per alcuni codici di errore, è consigliata una struttura JSON specifica per l'array messages nella risposta. Questi esempi sono forniti nella sezione Esempi di codici di errore sotto la tabella. In questi esempi, devi utilizzare il campo path per fornire informazioni più specifiche sulla posizione dell'errore all'interno dell'oggetto della richiesta o della risposta.

Gestione degli errori

La modalità di segnalazione degli errori dipende dal tipo di errore:

  • Errori di protocollo/server :

    • Utilizza i codici di stato HTTP standard (ad es. 4xx per gli errori del client, 5xx per gli errori del server) per problemi come richieste non valide, errori di autenticazione o indisponibilità del server.
    • Per maggiori dettagli, consulta la specifica UCP.

  • Errori/avvisi di logica di business :

    • Restituisci uno stato HTTP 200 OK. Sono inclusi i rifiuti di pagamento e i rifiuti per frode, anche se il gateway di pagamento downstream restituisce un errore 4xx o 5xx.
    • Descrivi il problema all'interno dell'array messages nel corpo della risposta JSON.
    • Ogni oggetto nell'array messages deve includere:
      • type: "error" o "warning"
      • code: un codice standardizzato di questa guida. Non utilizzare codici generici o non riconosciuti come "invalid".
      • content: una descrizione leggibile da una persona.
      • severity: obbligatorio quando type è "error". Questo campo indica esplicitamente se l'errore è terminale (unrecoverable) o ti consente di chiedere all'acquirente di correggere il problema (recoverable), anziché fare affidamento sul codice di errore stesso.

Tipi di messaggi: errore e avviso

Il campo type nell'array dei messaggi indica la gravità del problema. UCP definisce due tipi principali:

  • error: indica che l'operazione richiesta non è stata completata. È probabile che la piattaforma o l'utente debba intervenire e riprovare. Consulta la specifica message-error.
    • La natura terminale di un errore è determinata dal campo severity (unrecoverable o recoverable), non dall'errore code.
  • warning: indica che l'operazione non è stata bloccata, ma c'è qualcosa di importante che deve essere comunicato all'utente. Questo non interrompe il processo, ma fornisce un contesto importante. Consulta la specifica message-warning.

Messaggio del codice di errore

Codice di errore Tipo consigliato Descrizione
out_of_stock Errore L'articolo non è disponibile. In genere, questo comporta ucp.status: “error”. Utilizza il campo path per indicare l'indice dell'articolo nei pagamenti multi-articolo. Vedi esempio di seguito.
item_unavailable Errore Impossibile trovare l'articolo. In genere, questi errori relativi agli articoli comportano ucp.status: “error”.
item_ineligible Errore L'articolo esiste, ma non può essere acquistato utilizzando UCP.
quantity_invalid_limit_exceeded Errore La quantità richiesta supera il limite consentito. Vedi esempio di seguito.
quantity_invalid_minimum_not_met Errore La quantità richiesta è inferiore al minimo richiesto.
totals_changed Avviso Il prezzo o altri totali sono cambiati rispetto al passaggio precedente. Utilizza il campo path per indicare quale totale è cambiato. Vedi esempio di seguito.
totals_invalid_minimum_not_met Errore Il valore dell'ordine non soddisfa il requisito minimo.
missing_buyer_info Errore Mancano le informazioni obbligatorie sull'acquirente. Utilizza il campo path per specificare il campo mancante. Vedi esempio di seguito.
address_undeliverable Errore Si tratta di un codice di errore UCP standard. Utilizza il campo path per indicare la destinazione specifica o l'articolo con limitazioni. Vedi esempio di seguito.
address_unverifiable Errore Impossibile verificare l'indirizzo fornito. Utilizza il campo path per indicare se si tratta dell'indirizzo di evasione degli ordini o di fatturazione. Vedi esempio di seguito.
missing_fulfillment_info Errore Mancano le informazioni obbligatorie sull'evasione degli ordini. Utilizza il campo path per specificare il campo mancante.
eligibility_invalid Errore L'utente o l'ordine non è idoneo per l'azione. Si tratta di un codice di errore UCP standard. Utilizza il campo path per i dettagli.
discount_code_invalid Avviso Il codice sconto non è valido. Codice non trovato o non valido.
discount_code_expired Avviso Il codice sconto è scaduto.
discount_code_already_applied Avviso Il codice sconto è già stato applicato.
discount_code_combination_disallowed Avviso Il codice sconto non è cumulabile con altre offerte.
discount_code_user_not_logged_in Avviso L'utente deve aver eseguito l'accesso per utilizzare il codice sconto.
discount_code_user_ineligible Avviso L'utente non è idoneo a utilizzare il codice sconto.
missing_billing_info Errore Mancano i dati di fatturazione obbligatori. Utilizza il campo path per specificare i campi dell'indirizzo di fatturazione mancanti. Vedi esempio di seguito.
identity_required Errore L'identità dell'utente è obbligatoria per l'operazione richiesta, ma era assente, non valida, scaduta o non verificabile. Per REST, utilizza il codice di stato 401. Vedi esempio di seguito.
insufficient_scope Errore Il token di identità dell'utente è valido, ma non ha gli ambiti richiesti dall'operazione. Per REST, utilizza il codice di stato 403. Vedi esempio di seguito.
payment_declined Errore Il pagamento è stato rifiutato dall'emittente della carta o dalla banca. I motivi possono includere fondi insufficienti, sospetto di frode o problemi con la carta. Vedi esempio di seguito.
payment_failed Errore Il pagamento non è andato a buon fine a causa di un problema tecnico durante l'elaborazione, ad esempio un errore di rete, un timeout del gateway o un problema di integrazione, che ha impedito alla banca di prendere una decisione.
payment_ineligible Errore Il metodo di pagamento selezionato non è accettato. Adatto per i casi in cui l'utente deve provare un altro metodo di pagamento.
rejected_for_fraud Errore L'ordine è stato rifiutato a causa di sospetti di frode. Vedi esempio di seguito.

Esempi di codici di errore

Questa sezione fornisce esempi JSON per l'array messages per codici di errore specifici.

out_of_stock

Pagamento di un singolo articolo:

{
  "type": "error",
  "severity": "unrecoverable",
  "code": "out_of_stock",
  "content": "Unfortunately, the item 'Example Product 1' is out of stock."
}

Pagamento di più articoli:

Utilizza il campo path per indicare l'indice dell'articolo specifico non disponibile.

{
  "type": "error",
  "severity": "recoverable",
  "code": "out_of_stock",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' is out of stock. Remove it from your cart to continue."
}

quantity_invalid_limit_exceeded

{
  "type": "error",
  "severity": "recoverable",
  "code": "quantity_invalid_limit_exceeded",
  "path": "$.checkout.line_items[0].quantity",
  "content": "The requested quantity for 'Example Product 2' exceeds the maximum allowed limit of 5."
}

totals_changed

{
  "type": "warning",
  "code": "totals_changed",
  "path": "$.totals[2]",
  "content": "Shipping cost has changed."
}

missing_buyer_info

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_buyer_info",
  "path": "$.buyer.first_name",
  "content": "Missing buyer first name."
}

address_undeliverable

Restrizione a livello di ordine (ad es. codice postale non supportato):

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "content": "Delivery is not supported for the provided zipcode."
}

Restrizione a livello di articolo:

Utilizza il campo path per indicare un articolo specifico che non può essere consegnato alla destinazione scelta (ad es. divieti specifici per stato).

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' cannot be delivered to the selected address."
}

address_unverifiable

Indirizzo di fatturazione:

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.payment.instruments[0].billing_address",
  "content": "Invalid billing address. Update the address before trying again."
}

Indirizzo di evasione degli ordini:

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.fulfillment.methods[0].destinations[0]",
  "content": "The fulfillment address couldn't be verified. Update the address and try again."
}

missing_billing_info

Utilizza il campo path per specificare i campi mancanti all'interno dell'indirizzo di fatturazione.

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_billing_info",
  "path": "$.payment.instruments[0].billing_address.street_address",
  "content": "Missing billing street address."
}

identity_required

Nell'API REST, questo errore deve essere restituito con il codice di stato HTTP 401.

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "identity_required",
  "content": "User identity is required to access order history."
}

insufficient_scope

Nell'API REST, questo errore deve essere restituito con il codice di stato HTTP 403.

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "insufficient_scope",
  "content": "This operation requires scopes: dev.ucp.shopping.order:read, dev.ucp.shopping.order:manage"
}

Errori di pagamento

payment_declined

{
  "type": "error",
  "severity": "recoverable",
  "code": "payment_declined",
  "path": "$.payment.instruments[0]",
  "content": "Payment was declined by the issuer. Try a different payment method or contact your bank."
}

rejected_for_fraud

{
  "type": "error",
  "severity": "recoverable",
  "code": "rejected_for_fraud",
  "path": "$.payment.instruments[0]",
  "content": "The order was rejected due to suspected fraud. Try a different payment method."
}