Fehlerantworten verarbeiten

In diesem Leitfaden wird erläutert, wie Sie mit Fehlern umgehen, die von der Merchant API zurückgegeben werden. Die Struktur und Stabilität von Fehlerantworten zu verstehen, ist entscheidend für die Entwicklung robuster Integrationen, die sich automatisch von Fehlern erholen oder Nutzern aussagekräftiges Feedback geben können.

Übersicht

Wenn eine Merchant API-Anfrage fehlschlägt, gibt die API einen Standard-HTTP-Statuscode (4xx oder 5xx) und einen JSON-Antworttext mit Details zum Fehler zurück. Die Merchant API folgt dem AIP-193-Standard für Fehlerdetails und stellt maschinenlesbare Informationen bereit, mit denen Ihre Anwendung bestimmte Fehlerszenarien programmatisch verarbeiten kann.

Struktur der Fehlerantwort

Die Fehlerantwort ist ein JSON-Objekt, das Standardfelder wie code, message und status enthält. Wichtig ist, dass es auch ein details-Array enthält. Wenn Sie Fehler programmatisch beheben möchten, sollten Sie in details nach einem Objekt suchen, bei dem @type den Wert type.googleapis.com/google.rpc.ErrorInfo hat.

Dieses ErrorInfo-Objekt stellt stabile, strukturierte Daten zum Fehler bereit:

  • domain: Die logische Gruppierung des Fehlers, normalerweise merchantapi.googleapis.com.
  • metadata: Eine Zuordnung dynamischer Werte, die sich auf den Fehler beziehen. Dazu zählen:
    • REASON: Eine spezifische, stabile Kennung für den genauen Fehler (z.B. INVALID_NAME_PART_NOT_NUMBER, PERMISSION_DENIED_ACCOUNTS). Dieses Feld ist immer vorhanden. Verwenden Sie dieses Feld für eine detaillierte Fehlerbehandlung in Ihrer Anwendungslogik.
    • HELP_CENTER_LINK: Bietet zusätzlichen Kontext und Anleitungen zur Behebung des Problems. Dieses Feld ist nicht für alle Fehler vorhanden. Wir planen jedoch, es im Laufe der Zeit für die Fehler zu erweitern, bei denen möglicherweise mehr Kontext erforderlich ist.
    • Andere dynamische Felder: Andere Schlüssel, die Kontext liefern, z. B. der Name des ungültigen Felds (FIELD_LOCATION) oder der Wert, der den Fehler verursacht hat (FIELD_VALUE).

Beispiele für Fehlerantworten

Das folgende JSON-Beispiel zeigt die Struktur eines Merchant API-Fehlers, bei dem ein Ressourcenname fehlerhaft war.

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

Hier ein Beispiel für einen Authentifizierungsfehler:

{
  "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ät von Fehlerfeldern

Beim Schreiben der Logik für die Fehlerbehandlung ist es wichtig zu wissen, auf welche Felder Sie sich verlassen können und welche sich ändern können.

  • Stabile Felder:

  • details.metadata.REASON: Die spezifische Fehler-ID. Sie sollten dieses Feld für die Kontrollflusslogik Ihrer Anwendung verwenden.

    • details.metadata-Schlüssel: Die Schlüssel in der Metadatenzuordnung (z.B. FIELD_LOCATION, ACCOUNT_IDS) sind stabil.
    • code: Der allgemeine HTTP-Statuscode (z.B. 400, 401, 503) ist stabil.

  • Instabile Felder:

    • message: Die menschenlesbare Fehlermeldung ist nicht stabil. Sie ist nur für das Debugging durch Entwickler gedacht. Schreiben Sie keinen Code, der den Textinhalt des Felds message parst oder sich darauf verlässt, da er sich ohne Vorankündigung ändern kann, um die Klarheit zu verbessern oder Kontext hinzuzufügen.
    • details.metadata-Werte: Die Schlüssel sind stabil, aber die Werte für Informationsschlüssel können sich ändern. Wenn beispielsweise ein HELP_CENTER_LINK-Schlüssel angegeben wird, kann die spezifische URL, auf die er verweist, ohne vorherige Benachrichtigung auf eine neuere Dokumentationsseite aktualisiert werden. Wie bereits erwähnt, ist der Wert von details.metadata.REASON jedoch stabil.

Best Practices

Befolgen Sie diese Best Practices, um sicherzustellen, dass Ihre Integration Fehler ordnungsgemäß verarbeitet.

details.metadata.REASON für Logik verwenden

Verwenden Sie immer den spezifischen REASON in der metadata-Zuordnung, um die Ursache eines Fehlers zu ermitteln. Verlassen Sie sich nicht nur auf den HTTP-Statuscode, da mehrere Fehler denselben Statuscode haben können.

Fehlermeldung nicht parsen

Wie im Abschnitt zur Stabilität erwähnt, ist das Feld message für die menschliche Nutzung gedacht. Wenn Sie dynamische Informationen benötigen (z. B. welches Feld ungültig war), extrahieren Sie sie aus der metadata-Zuordnung mit stabilen Schlüsseln wie FIELD_LOCATION, VARIABLE_NAME.

Exponentiellen Backoff implementieren

Implementieren Sie bei Fehlern, die auf eine vorübergehende Nichtverfügbarkeit oder eine Ratenbegrenzung hinweisen, eine Strategie für exponentielles Backoff. Das bedeutet, dass Sie vor dem nächsten Versuch eine kurze Zeit warten und die Wartezeit nach jedem weiteren Fehler erhöhen.

  • quota/request_rate_too_high: Dieser Fehler weist darauf hin, dass Sie Ihr Minutenkontingent für eine bestimmte Kontingentgruppe überschritten haben. Verringern Sie die Anforderungsrate.
  • internal_error: Diese sind in der Regel vorübergehend. Wiederholungsversuche mit exponentiellem Backoff

Support für die Merchant API kontaktieren

Wenn Sie den Merchant API-Support wegen eines bestimmten Fehlers kontaktieren müssen, geben Sie in Ihrer Anfrage die folgenden Informationen an:

  1. Die genaue Fehlerantwort, die Sie erhalten haben
  2. Der Name der API-Methode
  3. Die Anfragenutzlast
  4. Zeitstempel oder Zeitraum, in dem die Methode aufgerufen wurde und Fehler empfangen wurden
Zurück
Track usage metrics
Weiter
Error messages