Fehlerantworten verarbeiten

In diesem Leitfaden wird beschrieben, wie Sie mit Fehlern umgehen, die von der Merchant API zurückgegeben werden. Es ist wichtig, die Struktur und Stabilität von Fehlerantworten zu verstehen, um robuste Integrationen zu entwickeln, 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 standardmäßigen 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 bietet maschinenlesbare Informationen, 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 verarbeiten möchten, sollten Sie in details nach einem Objekt suchen, dessen @type type.googleapis.com/google.rpc.ErrorInfo ist.

Dieses ErrorInfo-Objekt enthält stabile, strukturierte Daten zum Fehler:

  • Domain: Die logische Gruppierung des Fehlers, in der Regel merchantapi.googleapis.com.
  • metadata: Eine Karte mit dynamischen Werten, 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 die 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, die Abdeckung im Laufe der Zeit für die Fehler zu erweitern, bei denen mehr Kontext erforderlich sein könnte.
    • 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 formatiert wurde.

{
  "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 ist 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 von 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 sich für die Logik des Kontrollflusses Ihrer Anwendung auf dieses Feld verlassen.

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

  • Instabile Felder:

    • message: Die für Menschen lesbare Fehlermeldung ist nicht stabil. Es ist nur für das Debugging durch Entwickler vorgesehen. 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, die Werte für Informationsschlüssel können sich jedoch ä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, damit Ihre Integration Fehler ordnungsgemäß behandelt.

details.metadata.REASON für die Logik verwenden

Verwenden Sie immer das spezifische REASON in der metadata-Karte, 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 den menschlichen Gebrauch bestimmt. 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 und VARIABLE_NAME.

Exponentiellen Backoff implementieren

Bei Fehlern, die auf eine vorübergehende Nichtverfügbarkeit oder Ratenbegrenzung hinweisen, sollten Sie eine Strategie für exponentiellen Backoff implementieren. Das bedeutet, dass Sie vor dem erneuten Versuch eine kurze Zeit warten und die Wartezeit bei jedem nachfolgenden Fehler verlängern.

  • quota/request_rate_too_high: Dieser Fehler weist darauf hin, dass Sie Ihr Minutenkontingent für eine bestimmte Kontingentgruppe überschritten haben. Verringern Sie die Anfragerate.
  • internal_error: Diese sind in der Regel vorübergehend. Wiederholen Sie den Vorgang mit exponentiellem Backoff. Hinweis:Wenn internal_error nach mehreren Wiederholungsversuchen mit Backoff weiterhin auftritt, lesen Sie den Abschnitt Support für die Merchant API kontaktieren.

Support für Merchant APIs kontaktieren

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

  1. Die genaue erhaltene Fehlermeldung
  2. Der API-Methodenname
  3. Die Nutzlast der Anfrage
  4. Zeitstempel oder Zeitraum, in dem die Methode aufgerufen wurde und Fehler empfangen wurden