Fehlerantworten verarbeiten

In diesem Leitfaden wird erläutert, wie Sie mit Fehlern umgehen, die von der Merchant API zurückgegeben werden. Es ist wichtig, die Struktur und Stabilität der Fehlerantwort 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 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 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. Außerdem enthält sie ein details-Array. Wenn Sie Fehler programmatisch verarbeiten möchten, suchen Sie in details nach einem Objekt, bei dem @type auf type.googleapis.com/google.rpc.ErrorInfo festgelegt 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 Map mit dynamischen Werten im Zusammenhang mit dem Fehler. Dazu gehören:
  • 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 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 zeigt die Struktur eines Merchant API-Fehlers, bei dem ein Ressourcenname falsch formatiert 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 von Fehlerbehandlungslogik 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. Verlassen Sie sich bei der Logik für den Kontrollfluss Ihrer Anwendung auf dieses Feld.

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

• Instabile Felder :

  • message: Die für Menschen lesbare Fehlermeldung ist nicht stabil. Sie 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. Er kann ohne Vorankündigung geändert werden, um die Klarheit zu verbessern oder Kontext hinzuzufügen.
  • details.metadata values: Während die Schlüssel stabil sind, können sich die Werte für Informationsschlüssel ändern. Wenn beispielsweise ein HELP_CENTER_LINK-Schlüssel angegeben wird, kann die 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

Beachten Sie diese Best Practices, damit Ihre Integration Fehler ordnungsgemäß verarbeitet.

details.metadata.REASON für Logik verwenden

Verwenden Sie immer den spezifischen REASON in der metadata-Map, 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 Menschen bestimmt. Wenn Sie dynamische Informationen benötigen (z. B. welches Feld ungültig war), extrahieren Sie sie aus der metadata-Map mit stabilen Schlüsseln wie FIELD_LOCATION und VARIABLE_NAME.

Exponentiellen Backoff implementieren

Bei Fehlern, die auf eine vorübergehende Nichtverfügbarkeit oder eine Ratenbegrenzung hinweisen, sollten Sie eine exponentielle Backoff-Strategie implementieren. Das bedeutet, dass Sie vor dem Wiederholen 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 Fehler 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 Merchant API-Support kontaktieren.

Merchant API-Support 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 Fehlerantwort, die Sie erhalten haben
2. Der API-Methodenname
3. Die Anfragenutzlast
4. Zeitstempel oder der Zeitraum, in dem die Methode aufgerufen und Fehler empfangen wurden