Informazioni sugli errori API

Questa guida spiega come l'API Data Manager gestisce e comunica gli errori. Comprendere la struttura e il significato degli errori dell'API è fondamentale per creare applicazioni solide in grado di gestire correttamente i problemi, dall'input non valido alla temporanea indisponibilità del servizio.

L'API Data Manager segue il modello di errore standard delle API di Google, basato sui codici di stato gRPC. Ogni risposta dell'API che genera un errore include un oggetto Status con:

  • Un codice di errore numerico.
  • Un messaggio di errore.
  • Dettagli aggiuntivi facoltativi sull'errore.

Codici di errore canonici

L'API Data Manager utilizza un insieme di codici di errore canonici definiti da gRPC e HTTP. Questi codici forniscono un'indicazione generale del tipo di errore. Devi sempre controllare prima questo codice per comprendere la natura fondamentale del problema.

Per maggiori dettagli su questi codici, consulta la Guida alla progettazione delle API - Codici di errore.

Modello fast-fail

L'API Data Manager utilizza un modello di fail-fast. Se una richiesta contiene errori strutturali o se un record non supera la convalida per un campo obbligatorio, l'intera richiesta non va a buon fine e l'API non elabora i dati della richiesta.

Confronto con il modello di errore parziale

Il modello di errore rapido è diverso dal modello di errore parziale di alcune altre API di Google, come l'API Google Ads e l'API Campaign Manager 360. Nel modello di errore parziale, una richiesta ha esito positivo anche se alcuni record presentano errori e la risposta contiene i dettagli degli errori per i record con errori.

Sebbene l'errore parziale possa essere conveniente, comporta rischi significativi perché il modello di errore parziale non ti avvisa proattivamente degli errori: devi verificare esplicitamente la presenza di errori in ogni risposta. Ciò può mascherare problemi importanti, perché una richiesta va a buon fine anche se l'API rifiuta molti o addirittura tutti i record della richiesta. Se una parte significativa dei record di una richiesta contiene errori, ma non esamini la risposta, potresti non essere a conoscenza di problemi diffusi con i tuoi dati e scoprirli solo giorni o settimane dopo, quando i risultati cumulativi non sono in linea con le tue aspettative.

Il modello di errore rapido evita queste insidie avvisandoti immediatamente dei problemi relativi ai dati o all'integrazione, in modo che tu possa intraprendere l'azione appropriata.

Controlla la presenza di errori di tipo "fast-fail" con validateOnly

La maggior parte delle richieste di importazione e rimozione supporta un campo validateOnly. Quando imposti validateOnly su true, l'API Data Manager esegue gli stessi controlli di convalida di base di una richiesta normale, ma non importa né rimuove alcun dato.

  • Se la richiesta contiene errori, non va a buon fine e restituisce la stessa risposta di errore che riceveresti da una richiesta normale.
  • Se la richiesta supera la convalida, l'operazione va a buon fine. La risposta include eventuali fieldWarnings per i campi facoltativi, proprio come una richiesta normale.

Usa validateOnly per:

  • Testare un'integrazione nuova o aggiornata senza influire sui dati pubblicati.
  • Verifica che una correzione risolva un errore prima di inviare nuovamente la richiesta.

Gestisci gli errori

Se una richiesta non va a buon fine, segui questi passaggi:

  1. Controlla il codice di errore per trovare il tipo di errore.

    • Se utilizzi gRPC, il codice di errore si trova nel campo code di Status. Se utilizzi una libreria client, potrebbe essere generato un tipo specifico di eccezione corrispondente al codice di errore. Ad esempio, la libreria client per Java genera un'eccezione com.google.api.gax.rpc.InvalidArgumentException se il codice di errore è INVALID_ARGUMENT.
    • Se utilizzi REST, il codice di errore si trova nella risposta di errore in error.status, mentre lo stato HTTP corrispondente si trova in error.code.

  2. Controlla il payload dei dettagli standard per il codice di errore. I payload dei dettagli standard sono un insieme di messaggi per gli errori delle API di Google. Forniscono i dettagli degli errori in modo strutturato e coerente. Ogni errore dell'API Data Manager può avere più messaggi di payload dei dettagli standard. Le librerie client dell'API Data Manager dispongono di metodi helper per ottenere i payload dei dettagli standard da un errore.

    Indipendentemente dal codice di errore, ti consigliamo di verificare e registrare i payload ErrorInfo, RequestInfo, Help e LocalizedMessage.

    • ErrorInfo contiene informazioni che potrebbero non essere presenti in altri payload.
    • RequestInfo contiene l'ID richiesta, che è utile se devi contattare l'assistenza.
    • Help e LocalizedMessage contengono link e altri dettagli per aiutarti a risolvere l'errore.

    Inoltre, il payload BadRequest è utile per gli errori INVALID_ARGUMENT, poiché fornisce informazioni sui campi che hanno causato l'errore.

Avvisi di importazione

L'API Data Manager accetta la maggior parte possibile di una richiesta di importazione. Se includi dati non obbligatori, gli errori di convalida di questi campi non causeranno l'errore della richiesta. Ad esempio, se a un articolo del carrello manca un ID prodotto del commerciante, l'API elabora il resto della richiesta e restituisce un avviso.

Una risposta di importazione riuscita (codice di stato HTTP 200) include questi avvisi in un elenco fieldWarnings. Ogni voce è un oggetto FieldWarning con i seguenti campi:

field

La posizione del campo nella richiesta, nella sintassi del percorso snake_case.

Se un percorso rimanda a un elemento di un elenco (un campo repeated), il suo indice viene mostrato tra parentesi quadre ([...]) dopo il nome dell'elenco.

Ad esempio, events.events[0].cart_data.items[0].merchant_product_id identifica un avviso relativo al primo articolo nei dati del carrello del primo evento della richiesta.

description

Una spiegazione del motivo per cui il valore fornito ha generato un avviso.

reason

Il valore dell'enum WarningReason che identifica il tipo di avviso.

Esempio con FieldWarning

Di seguito è riportato un esempio di risposta per una richiesta di importazione andata a buon fine che contiene un avviso perché mancava un ID prodotto del commerciante per uno degli articoli del carrello.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a",
  "fieldWarnings": [
    {
      "field": "events.events[0].cart_data.items[0].merchant_product_id",
      "description": "The merchant product ID is missing in the cart item.",
      "reason": "WARNING_REASON_CART_DATA_ITEM_MERCHANT_PRODUCT_ID_MISSING"
    }
  ]
}

Payload dei dettagli standard

I payload dei dettagli standard più comuni per l'API Data Manager sono:

BadRequest

Controlla il payload BadRequest quando una richiesta non va a buon fine con INVALID_ARGUMENT (codice di stato HTTP 400).

Un messaggio BadRequest indica che la richiesta conteneva campi con valori errati o che mancava un valore per un campo obbligatorio. Controlla l'elenco field_violations in BadRequest per scoprire quali campi contengono errori. Ogni voce field_violations contiene informazioni che ti aiutano a correggere l'errore:

field

La posizione del campo nella richiesta, nella sintassi del percorso snake_case.

Se un percorso rimanda a un elemento di un elenco (un campo repeated), il suo indice viene mostrato tra parentesi quadre ([...]) dopo il nome dell'elenco.

Ad esempio, destinations[0].operating_account.account_id è il account_id nel operating_account del primo elemento nell'elenco destinations.

description

Una spiegazione del motivo per cui il valore ha causato un errore.

reason

L'enum ErrorReason, ad esempio INVALID_HEX_ENCODING o INVALID_CURRENCY_CODE.

Esempi di: BadRequest

Ecco un esempio di risposta per un errore INVALID_ARGUMENT con un messaggio BadRequest. field_violations mostra che l'errore è un accountId che non è un numero. Il valore field destinations[0].login_account.account_id mostra che il accountId con una violazione del campo si trova nel login_account del primo elemento nell'elenco destinations.

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com",
        "metadata": {
          "requestId": "t-a8896317-069f-4198-afed-182a3872a660"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "t-a8896317-069f-4198-afed-182a3872a660"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "destinations[0].login_account.account_id",
            "description": "String is not a valid number.",
            "reason": "INVALID_NUMBER_FORMAT"
          }
        ]
      }
    ]
  }
}

Ecco un altro esempio di risposta di un errore INVALID_ARGUMENT con un messaggio BadRequest. In questo caso, l'elenco field_violations mostra due errori:

  1. Il primo event ha un valore non codificato in formato esadecimale nel secondo identificatore dell'utente dell'evento.

  2. Il secondo event ha un valore non codificato in formato esadecimale nel terzo identificatore dell'utente dell'evento.

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com",
        "metadata": {
          "requestId": "t-6bc8fb83-d648-4942-9c49-2604276638d8"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "t-6bc8fb83-d648-4942-9c49-2604276638d8"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers[1]",
            "description": "The HEX encoded value is malformed.",
            "reason": "INVALID_HEX_ENCODING"
          },
          {
            "field": "events.events[1].user_data.user_identifiers[2]",
            "description": "The HEX encoded value is malformed.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

RequestInfo

Controlla il payload RequestInfo ogni volta che una richiesta non va a buon fine. Un RequestInfo contiene l'request_id che identifica in modo univoco la tua richiesta API.

{
  "@type": "type.googleapis.com/google.rpc.RequestInfo",
  "requestId": "t-4490c640-dc5d-4c28-91c1-04a1cae0f49f"
}

Quando registri gli errori o contatti l'assistenza, assicurati di includere l'ID richiesta per facilitare la diagnosi dei problemi.

ErrorInfo

Controlla il messaggio ErrorInfo per recuperare informazioni aggiuntive che potrebbero non essere acquisite negli altri payload dei dettagli standard. Il payload ErrorInfo contiene una mappa metadata con informazioni sull'errore.

Ad esempio, ecco il ErrorInfo per un errore PERMISSION_DENIED causato dall'utilizzo delle credenziali per un progetto Google Cloud in cui l'API Data Manager non è abilitata. Il campo ErrorInfo fornisce ulteriori informazioni sull'errore, ad esempio:

  • Il progetto associato alla richiesta, in metadata.consumer.
  • Il nome del servizio, in metadata.serviceTitle.
  • L'URL in cui è possibile attivare il servizio, in metadata.activationUrl.
{
  "error": {
    "code": 403,
    "message": "Data Manager API has not been used in project PROJECT_NUMBER before or it is disabled. Enable it by visiting https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "SERVICE_DISABLED",
        "domain": "googleapis.com",
        "metadata": {
          "consumer": "projects/PROJECT_NUMBER",
          "service": "datamanager.googleapis.com",
          "containerInfo": "PROJECT_NUMBER",
          "serviceTitle": "Data Manager API",
          "activationUrl": "https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER"
        }
      },
      ...
    ]
  }
}

Errori relativi a quote e limiti di frequenza

Quando una richiesta supera un limite del progetto, l'API restituisce un errore RESOURCE_EXHAUSTED (codice di stato HTTP 429). Il payload ErrorInfo fornisce dettagli su quale limite è stato superato nella mappa metadata:

consumer
Il progetto Google Cloud associato alla richiesta, formattato come projects/PROJECT_NUMBER.
quota_limit
Il nome del limite di quota superato, ad esempio IngestionMutateRequestsPerMinutePerProject o IngestionMutateRequestsPerDayPerProject. Puoi utilizzare questo valore per determinare se l'applicazione ha superato un limite al minuto o un limite giornaliero. Per l'elenco completo dei nomi dei limiti, consulta Limiti dei progetti.
quota_location
La località in cui viene applicata la quota. Per l'API Data Manager, questo valore è sempre global.
quota_metric
La metrica associata al limite, ad esempio datamanager.googleapis.com/ingestion_mutate_requests.
service
Il nome del servizio, datamanager.googleapis.com.

Di seguito è riportato un esempio di risposta di errore RESOURCE_EXHAUSTED quando una richiesta supera il limite al minuto per le richieste di modifica dell'importazione:

{
  "error": {
    "code": 429,
    "message": "Quota exceeded for quota metric 'Ingestion mutate requests' and limit 'Ingestion mutate requests per minute' of service 'datamanager.googleapis.com' for consumer 'project_number:PROJECT_NUMBER'.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RATE_LIMIT_EXCEEDED",
        "domain": "googleapis.com",
        "metadata": {
          "consumer": "projects/PROJECT_NUMBER",
          "quota_limit": "IngestionMutateRequestsPerMinutePerProject",
          "quota_location": "global",
          "quota_metric": "datamanager.googleapis.com/ingestion_mutate_requests",
          "service": "datamanager.googleapis.com"
        }
      }
    ]
  }
}

Help e LocalizedMessage

Controlla i payload Help e LocalizedMessage per ottenere i link alla documentazione e ai messaggi di errore localizzati che ti aiutano a comprendere e correggere l'errore.

Ad esempio, di seguito sono riportati Help e LocalizedMessage per un errore PERMISSION_DENIED causato dall'utilizzo delle credenziali per un progetto cloud Google in cui l'API Data Manager non è abilitata. Il payload Help mostra l'URL in cui è possibile attivare il servizio e LocalizedMessage contiene una descrizione dell'errore.

{
  "error": {
    "code": 403,
    "message": "Data Manager API has not been used in project PROJECT_NUMBER before or it is disabled. Enable it by visiting https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "Data Manager API has not been used in project PROJECT_NUMBER before or it is disabled. Enable it by visiting https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry."
      },
      {
        "@type": "type.googleapis.com/google.rpc.Help",
        "links": [
          {
            "description": "Google API Console API activation",
            "url": "https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER"
          }
        ]
      },
      ...
    ]
  }
}

Dettagli dell'errore di accesso

Se utilizzi una delle librerie client, utilizza i metodi helper per ottenere i payload dei dettagli standard.

.NET

try {
    // Send API request
}
catch (Grpc.Core.RpcException rpcException)
{
    Console.WriteLine($"Exception encountered: {rpcException.Message}");
    var statusDetails =
        Google.Api.Gax.Grpc.RpcExceptionExtensions.GetAllStatusDetails(
            rpcException
        );
    foreach (var detail in statusDetails)
    {
        if (detail is Google.Rpc.BadRequest)
        {
            Google.Rpc.BadRequest badRequest = (Google.Rpc.BadRequest)detail;
            foreach (
                BadRequest.Types.FieldViolation? fieldViolation in badRequest.FieldViolations
            )
            {
                // Access attributes such as fieldViolation!.Reason and fieldViolation!.Field
            }
        }
        else if (detail is Google.Rpc.RequestInfo)
        {
            Google.Rpc.RequestInfo requestInfo = (Google.Rpc.RequestInfo)detail;
            string requestId = requestInfo.RequestId;
            // Log the requestId...
        }
        else if (detail is Google.Rpc.ErrorInfo)
        {
            Google.Rpc.ErrorInfo errorInfo = (Google.Rpc.ErrorInfo)detail;
            // Log the errorInfo.Reason and errorInfo.Metadata...

            // If handling a rate limit error, check the exceeded quota limit:
            if (errorInfo.Reason == "RATE_LIMIT_EXCEEDED" &&
                errorInfo.Metadata.TryGetValue("quota_limit", out string quotaLimit))
            {
                // Inspect quotaLimit to determine whether it is a per-minute
                // or daily limit (for example,
                // IngestionMutateRequestsPerMinutePerProject).
            }

            // Log the details in the 'Metadata' map...
            foreach (
                KeyValuePair<String, String> metadataEntry in errorInfo.Metadata
            )
            {
                // Log the metadataEntry.Key and metadataEntry.Value...
            }
        }
        else
        {
            // ...
        }
    }
}

Java

try {
  // Send API request
} catch (com.google.api.gax.rpc.InvalidArgumentException invalidArgumentException) {
  // Gets the standard BadRequest payload from the exception.
  BadRequest badRequest = invalidArgumentException.getErrorDetails().getBadRequest();
  for (int i = 0; i < badRequest.getFieldViolationsCount(); i++) {
    FieldViolation fieldViolation = badRequest.getFieldViolations(i);
    // Access attributes such as fieldViolation.getField() and fieldViolation.getReason()
  }

  // Gets the standard RequestInfo payload from the exception.
  RequestInfo requestInfo = invalidArgumentException.getErrorDetails().getRequestInfo();
  if (requestInfo != null) {
    String requestId = requestInfo.getRequestId();
    // Log the requestId...
  }
} catch (com.google.api.gax.rpc.ApiException apiException) {
  // Fallback exception handler for other types of ApiException.

  // Gets the standard ErrorInfo payload from the exception.
  ErrorInfo errorInfo = apiException.getErrorDetails().getErrorInfo();
  // Log the 'reason' and 'domain'...

  // If handling a rate limit error, check the exceeded quota limit:
  if (errorInfo != null && "RATE_LIMIT_EXCEEDED".equals(errorInfo.getReason())) {
    String quotaLimit = errorInfo.getMetadataMap().get("quota_limit");
    // Inspect quotaLimit to determine whether it is a per-minute
    // or daily limit (for example,
    // IngestionMutateRequestsPerMinutePerProject).
  }

  // Log the details in the 'metadata' map...
  for (Entry<String, String> metadataEntry : errorInfo.getMetadataMap().entrySet()) {
    // Log the metadataEntry key and value...
  }

  // Gets the standard RequestInfo payload from the exception.
  RequestInfo requestInfo = apiException.getErrorDetails().getRequestInfo();
  if (requestInfo != null) {
    String requestId = requestInfo.getRequestId();
    // Log the requestId...
  }
  ...
}

Gestisci gli errori relativi alle dimensioni dell'intestazione per gRPC

Quando un numero elevato di record in una richiesta di importazione o rimozione non supera la convalida, l'API Data Manager restituisce tutti gli errori nel payload BadRequest della risposta.

In gRPC, il servizio restituisce questi dettagli dell'errore nelle intestazioni della risposta HTTP/2 (metadati). Per impostazione predefinita, le librerie client gRPC limitano le intestazioni in entrata a una dimensione massima (in genere 8-10 kB). Se i dettagli dell'errore superano questo limite, il trasporto HTTP/2 lato client non va a buon fine prima di analizzare la risposta di errore, generando un'eccezione come:

Http2Exception: Header size exceeded max allowed size (10240)

Poiché il client non può elaborare le intestazioni della risposta, annulla lo stream (che viene visualizzato come stato HTTP 499 Client Closed Request nei log lato server) e la tua applicazione non può accedere ai dettagli dell'errore BadRequest.

Per risolvere il problema e ispezionare l'elenco completo degli errori, configura il client gRPC con una dimensione massima dei metadati in entrata aumentata (ad esempio 16 MB):

.NET

// Creates a client for the ingestion service. Increases the maximum metadata size to
// 16MB to prevent RESOURCE_EXHAUSTED errors when responses contain large error
// details.
IngestionServiceClient ingestionServiceClient = new IngestionServiceClientBuilder
{
    GrpcChannelOptions = GrpcChannelOptions.Empty.WithCustomOption(
        "grpc.max_metadata_size",
        16 * 1024 * 1024
    ),
}.Build();

Java

// Creates a client for the ingestion service. Increases the maximum metadata size to 16MB to
// prevent RESOURCE_EXHAUSTED errors when responses contain large error details.
InstantiatingGrpcChannelProvider provider =
    IngestionServiceSettings.defaultGrpcTransportProviderBuilder()
        .setMaxInboundMetadataSize(16 * 1024 * 1024)
        .build();
IngestionServiceSettings settings =
    IngestionServiceSettings.newBuilder().setTransportChannelProvider(provider).build();
try (IngestionServiceClient ingestionServiceClient = IngestionServiceClient.create(settings)) {
  // ...
}

Nodo

// Creates a client for the ingestion service. Increases the maximum metadata
// size to 16MB to prevent RESOURCE_EXHAUSTED errors when responses contain
// large error details.
const client = new IngestionServiceClient({
  'grpc.max_metadata_size': 16 * 1024 * 1024,
});

PHP

// Creates a client for the ingestion service. Increases the maximum metadata size to 16MB to
// prevent RESOURCE_EXHAUSTED errors when responses contain large error details.
$client = new IngestionServiceClient([
    'transportConfig' => [
        'grpc' => [
            'stubOpts' => [
                'grpc.max_metadata_size' => 16 * 1024 * 1024,
            ],
        ],
    ],
]);

Python

# Creates a client for the ingestion service. Increases the maximum
# metadata size to 16MB to prevent RESOURCE_EXHAUSTED errors when responses
# contain large error details.
channel = datamanager_v1.services.ingestion_service.transports.IngestionServiceGrpcTransport.create_channel(
    options=[("grpc.max_metadata_size", 16 * 1024 * 1024)]
)
transport = datamanager_v1.services.ingestion_service.transports.IngestionServiceGrpcTransport(
    channel=channel
)
client: datamanager_v1.IngestionServiceClient = (
    datamanager_v1.IngestionServiceClient(transport=transport)
)

Best practice per la gestione degli errori

Per creare applicazioni resilienti, implementa le seguenti best practice.

Convalida prima dell'invio
Quando crei o modifichi un'integrazione, invia richieste con validateOnly impostato su true per rilevare gli errori di tipo "fast-fail" prima di importare i dati.
Esamina i dettagli dell'errore
Cerca sempre uno dei payload dei dettagli standard, ad esempio BadRequest. Ogni payload dei dettagli standard contiene informazioni che ti aiutano a comprendere la causa dell'errore.
Differenzia gli errori del client da quelli del server

Determina se l'errore è causato da un problema con l'implementazione (il client) o con l'API (il server).

  • Errori del client: codici come INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. Questi errori richiedono modifiche alla richiesta o allo stato/alle credenziali dell'applicazione. Non riprovare a inviare la richiesta senza risolvere il problema.
  • Errori del server: codici come UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. Questi indicano un problema temporaneo con il servizio API.
Implementa una strategia di ripetizione dei tentativi

Determina se è possibile riprovare l'errore e utilizza una strategia di ripetizione.

  • Riprova solo per gli errori temporanei del server (come UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN e ABORTED) e per i limiti di frequenza al minuto (RESOURCE_EXHAUSTED con RATE_LIMIT_EXCEEDED).

  • Per i limiti di frequenza, controlla quota_limit in ErrorInfo:

    • Se il limite è al minuto (ad esempio IngestionMutateRequestsPerMinutePerProject), metti in pausa le richieste e riprova utilizzando il backoff esponenziale con jitter.

    • Se il limite è giornaliero (ad esempio IngestionMutateRequestsPerDayPerProject), non riprovare immediatamente. Metti in pausa l'elaborazione fino a quando la quota giornaliera non viene reimpostata alla mezzanotte del fuso orario del Pacifico.

  • Utilizza un algoritmo di backoff esponenziale per attendere periodi di tempo crescenti tra i nuovi tentativi. In questo modo si evita di sovraccaricare un servizio già sotto stress. Ad esempio, attendi 1 secondo, poi 2 secondi, poi 4 secondi, continuando fino a un numero massimo di nuovi tentativi o un tempo di attesa totale.

  • Aggiungi una piccola quantità casuale di "jitter" ai ritardi di backoff per evitare il problema del "thundering herd", in cui molti client riprovano contemporaneamente.

Registra attentamente

Registra la risposta di errore completa, inclusi tutti i payload dei dettagli standard, in particolare l'ID richiesta. Queste informazioni sono essenziali per il debug e la segnalazione di problemi all'Assistenza Google, se necessario.

Fornisci feedback degli utenti

In base ai codici e ai messaggi nei payload dei dettagli standard, fornisci un feedback chiaro e utile agli utenti della tua applicazione. Ad esempio, anziché limitarti a "Si è verificato un errore", puoi dire "ID transazione mancante" o "ID account della destinazione non trovato".

Se segui queste linee guida, puoi diagnosticare e gestire in modo efficace gli errori restituiti dall'API Data Manager, creando applicazioni più stabili e facili da usare.

Indietro
Cripta i dati utente
Avanti
Best practice