Diese Seite wurde von der Cloud Translation API übersetzt.

API-Fehler verstehen

In diesem Leitfaden wird beschrieben, wie die Data Manager API Fehler verarbeitet und kommuniziert. Die Struktur und Bedeutung von API-Fehlern zu verstehen, ist entscheidend für die Entwicklung robuster Anwendungen, die Probleme wie ungültige Eingaben oder vorübergehende Dienstausfälle problemlos bewältigen können.

Die Data Manager API folgt dem Standardfehlermodell von Google APIs, das auf gRPC-Statuscodes basiert. Jede API-Antwort, die zu einem Fehler führt, enthält ein Status-Objekt mit:

Ein numerischer Fehlercode.
Eine Fehlermeldung.
Optionale zusätzliche Fehlerdetails.

Kanonische Fehlercodes

Für die Data Manager API wird eine Reihe von kanonischen Fehlercodes verwendet, die von gRPC und HTTP definiert werden. Diese Codes geben einen allgemeinen Hinweis auf den Fehlertyp. Sie sollten diesen Code immer zuerst prüfen, um die grundlegende Art des Problems zu verstehen.

Weitere Informationen zu diesen Codes finden Sie im Leitfaden zum API-Design – Fehlercodes.

Fehler verarbeiten

Gehen Sie so vor, wenn eine Anfrage fehlschlägt:

Prüfen Sie den Fehlercode, um den Fehlertyp zu ermitteln.
- Wenn Sie gRPC verwenden, befindet sich der Fehlercode im Feld code des Status. Wenn Sie eine Clientbibliothek verwenden, wird möglicherweise ein bestimmter Ausnahmetyp ausgelöst, der dem Fehlercode entspricht. Die Clientbibliothek für Java löst beispielsweise eine com.google.api.gax.rpc.InvalidArgumentException aus, wenn der Fehlercode INVALID_ARGUMENT ist.
- Wenn Sie REST verwenden, befindet sich der Fehlercode in der Fehlerantwort unter error.status und der entsprechende HTTP-Status unter error.code.
Wichtig: Wenn eine Anfrage fehlschlägt, werden keine der Daten in der Anfrage von der Data Manager API verarbeitet. Beheben Sie die Fehlerursache und senden Sie die gesamte Anfrage noch einmal. Senden Sie nicht nur eine Anfrage mit den Zielgruppenmitgliedern oder Ereignissen, die zum Fehler geführt haben.
Suchen Sie nach der Standard-Detailnutzlast für den Fehlercode. Die Standardnutzlasten für Details sind eine Reihe von Meldungen für Fehler von Google APIs. Sie liefern Fehlerdetails auf strukturierte und einheitliche Weise. Für jeden Fehler aus der Data Manager API können mehrere Standard-Detail-Nutzlastmeldungen vorhanden sein. Die Data Manager API-Clientbibliotheken enthalten Hilfsmethoden, mit denen Sie die Standardnutzlasten mit detaillierten Informationen aus einem Fehler abrufen können.

Unabhängig vom Fehlercode empfehlen wir, die Nutzlasten ErrorInfo, RequestInfo, Help und LocalizedMessage} zu prüfen und zu protokollieren.
- ErrorInfo enthält Informationen, die möglicherweise nicht in anderen Nutzlasten enthalten sind.
- RequestInfo enthält die Anforderungs-ID, die hilfreich ist, wenn Sie den Support kontaktieren müssen.
- Help und LocalizedMessage enthalten Links und andere Details, die Ihnen bei der Behebung des Fehlers helfen.
Außerdem sind die Nutzlasten BadRequest, QuotaFailure und RetryInfo für bestimmte Fehlercodes nützlich:
- Wenn der Statuscode INVALID_ARGUMENT ist, prüfen Sie die Nutzlast BadRequest auf Informationen dazu, welche Felder den Fehler verursacht haben.
- Wenn der Statuscode RESOURCE_EXHAUSTED lautet, prüfen Sie die Nutzlasten QuotaFailure und RetryInfo auf Informationen zum Kontingent und eine Empfehlung für die Verzögerung von Wiederholungsversuchen.

Standardnutzlasten für Details

Die häufigsten Standard-Detailnutzlasten für die Data Manager API sind:

BadRequest
QuotaFailure und RetryInfo
RequestInfo
ErrorInfo
Help und LocalizedMessage

`BadRequest`

Prüfen Sie die BadRequest-Nutzlast, wenn eine Anfrage mit INVALID_ARGUMENT (HTTP-Statuscode 400) fehlschlägt.

Eine BadRequest-Meldung weist darauf hin, dass die Anfrage Felder mit ungültigen Werten enthielt oder ein Wert für ein erforderliches Feld fehlte. Sehen Sie sich die Liste field_violations im BadRequest an, um herauszufinden, in welchen Feldern Fehler auftreten. Jeder field_violations-Eintrag enthält Informationen, die Ihnen bei der Behebung des Fehlers helfen:

field

Die Position des Felds in der Anfrage mit einer Pfadsyntax in CamelCase.

Wenn ein Pfad auf ein Element in einer Liste (ein repeated-Feld) verweist, wird sein Index in eckigen Klammern ([...]) nach dem Namen der Liste angezeigt.

destinations[0].operating_account.account_id ist beispielsweise die account_id im operating_account des ersten Elements in der Liste destinations.

description

Eine Erklärung, warum der Wert einen Fehler verursacht hat.

reason

Die ErrorReason-Enumeration, z. B. INVALID_HEX_ENCODING oder INVALID_CURRENCY_CODE.

Beispiele für `BadRequest`

Hier sehen Sie eine Beispielantwort für einen INVALID_ARGUMENT-Fehler mit einer BadRequest-Meldung. Die field_violations zeigen, dass der Fehler ein accountId ist, das keine Zahl ist. Der Wert field destinations[0].login_account.account_id gibt an, dass die accountId mit einem Feldverstoß im login_account des ersten Elements in der destinations-Liste enthalten ist.

{
  "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"
          }
        ]
      }
    ]
  }
}

Hier sehen Sie ein weiteres Beispiel für eine Antwort auf einen INVALID_ARGUMENT-Fehler mit einer BadRequest-Nachricht. In diesem Fall enthält die Liste field_violations zwei Fehler:

Der erste event-Wert ist nicht hexadezimal codiert und befindet sich im zweiten Nutzer-Identifier des Ereignisses.
Die zweite event hat einen Wert, der nicht hexadezimal codiert ist, und zwar für die dritte User-ID des Ereignisses.

{
  "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"
          }
        ]
      }
    ]
  }
}

`QuotaFailure` und `RetryInfo`

Prüfen Sie bei einem Fehler einer Anfrage mit RESOURCE_EXHAUSTED (HTTP-Statuscode 429) die Nutzlasten QuotaFailure und RetryInfo.

Eine QuotaFailure-Meldung gibt an, dass entweder eine Ressource erschöpft ist (z. B. wenn Sie Ihr Kontingent überschritten haben) oder ein System überlastet ist. Sehen Sie sich die Liste der violations an, um festzustellen, welche Kontingente überschritten wurden.

Der Fehler kann auch eine RetryInfo-Nachricht enthalten, die ein empfohlenes retry_delay für den Wiederholungsversuch der Anfrage angibt.

`RequestInfo`

Prüfen Sie bei einem Fehler in einer Anfrage, ob die RequestInfo-Nutzlast vorhanden ist. Ein RequestInfo enthält die request_id, die Ihre API-Anfrage eindeutig identifiziert.

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

Wenn Sie Fehler protokollieren oder den Support kontaktieren, geben Sie unbedingt die Anfrage-ID an, damit Probleme leichter diagnostiziert werden können.

`ErrorInfo`

Suchen Sie nach der Meldung ErrorInfo, um zusätzliche Informationen abzurufen, die möglicherweise nicht in den anderen Standard-Detail-Nutzlasten enthalten sind. Die ErrorInfo-Nutzlast enthält eine metadata-Karte mit Informationen zum Fehler.

Hier sehen Sie beispielsweise die ErrorInfo für einen PERMISSION_DENIED-Fehler, der durch die Verwendung von Anmeldedaten für ein Google Cloud-Projekt verursacht wurde, in dem die Data Manager API nicht aktiviert ist. Der ErrorInfo enthält zusätzliche Informationen zum Fehler, z. B.:

Das mit der Anfrage verknüpfte Projekt unter metadata.consumer.
Der Name des Dienstes unter metadata.serviceTitle.
Die URL, unter der der Dienst unter metadata.activationUrl aktiviert werden kann.

{
  "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.developers.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.developers.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER"
        }
      },
      ...
    ]
  }
}

`Help` und `LocalizedMessage`

Suchen Sie nach den Nutzlasten Help und LocalizedMessage, um Links zur Dokumentation und lokalisierte Fehlermeldungen zu erhalten, die Ihnen helfen, den Fehler zu verstehen und zu beheben.

Hier sind beispielsweise die Help und LocalizedMessage für einen PERMISSION_DENIED-Fehler, der durch die Verwendung von Anmeldedaten für ein Google Cloud-Projekt verursacht wird, in dem die Data Manager API nicht aktiviert ist. Die Help-Nutzlast enthält die URL, unter der der Dienst aktiviert werden kann, und LocalizedMessage enthält eine Beschreibung des Fehlers.

{
  "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.developers.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.developers.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 developers console API activation",
            "url": "https://console.developers.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER"
          }
        ]
      },
      ...
    ]
  }
}

Auf Fehlerdetails zugreifen

Wenn Sie eine der Clientbibliotheken verwenden, können Sie die Standardnutzlasten mit den Hilfsmethoden abrufen.

.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.QuotaFailure)
        {
            Google.Rpc.QuotaFailure quotaFailure = (Google.Rpc.QuotaFailure)detail;
            foreach (
                Google.Rpc.QuotaFailure.Types.Violation violation in quotaFailure.Violations
            )
            {
                // Access attributes such as violation.Subject and violation.QuotaId
            }
        }
        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.QuotaFailureException quotaFailureException) {
  // Gets the standard QuotaFailure payload from the exception.
  QuotaFailure quotaFailure = quotaFailureException.getErrorDetails().getQuotaFailure();
  for (int i = 0; i < quotaFailure.getViolationsCount(); i++) {
    QuotaFailure.Violation violation = quotaFailure.getViolations(i);
    // Access attributes such as violation.getSubject() and violation.getQuotaId()
  }

  // Gets the standard RequestInfo payload from the exception.
  RequestInfo requestInfo = quotaFailureException.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.
  ...
}

Best Practices für die Fehlerbehandlung

Um robuste Anwendungen zu entwickeln, sollten Sie die folgenden Best Practices implementieren.

Fehlerdetails ansehen

Suchen Sie immer nach einer der Standard-Detailnutzlasten wie BadRequest. Jede Nutzlast mit Standarddetails enthält Informationen, die Ihnen helfen, die Ursache des Fehlers zu verstehen.

Client- und Serverfehler unterscheiden

Stellen Sie fest, ob der Fehler durch ein Problem mit Ihrer Implementierung (dem Client) oder mit der API (dem Server) verursacht wird.

Clientfehler: Codes wie INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. Dafür sind Änderungen am Antrag oder am Status/den Anmeldedaten Ihrer Anwendung erforderlich. Wiederholen Sie die Anfrage nicht, ohne das Problem zu beheben.
Serverfehler: Codes wie UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. Diese deuten auf ein vorübergehendes Problem mit dem API-Dienst hin.

Wiederholungsstrategie implementieren

Stellen Sie fest, ob der Fehler wiederholt werden kann, und verwenden Sie eine Wiederholungsstrategie.

Wiederholen Sie den Vorgang nur bei vorübergehenden Serverfehlern wie UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN und ABORTED.
Verwenden Sie einen exponentiellen Backoff-Algorithmus, um zwischen Wiederholungsversuchen immer länger zu warten. So wird verhindert, dass ein bereits überlasteter Dienst überfordert wird. Warten Sie beispielsweise 1 Sekunde, dann 2 Sekunden, dann 4 Sekunden usw. bis zu einer maximalen Anzahl von Wiederholungsversuchen oder einer maximalen Wartezeit.
Fügen Sie den Backoff-Verzögerungen eine kleine zufällige Menge an „Jitter“ hinzu, um das „Thundering-Herd-Problem“ zu vermeiden, bei dem viele Clients gleichzeitig Wiederholungsversuche starten.

Gründlich protokollieren

Protokollieren Sie die vollständige Fehlerantwort, einschließlich aller Standard-Detailnutzlasten, insbesondere der Anfrage-ID. Diese Informationen sind für die Fehlerbehebung und die Meldung von Problemen an den Google-Support erforderlich.

Nutzerfeedback geben

Geben Sie den Nutzern Ihrer Anwendung anhand der Codes und Nachrichten in den Standard-Detail-Nutzlasten klares und hilfreiches Feedback. Sagen Sie beispielsweise anstelle von „Es ist ein Fehler aufgetreten“ lieber „Die Transaktions-ID fehlt“ oder „Die Konto-ID des Ziels wurde nicht gefunden“.

Wenn Sie diese Richtlinien befolgen, können Sie Fehler, die von der Data Manager API zurückgegeben werden, effektiv diagnostizieren und beheben. So erhalten Sie stabilere und benutzerfreundlichere Anwendungen.

Zurück

Nutzerdaten verschlüsseln

Weiter

Best Practices

API-Fehler verstehen Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.