Fehlerantworten verarbeiten

In dieser Anleitung wird erläutert, wie Sie mit Fehlern umgehen, die von der Merchant API zurückgegeben werden. Das Verständnis der Struktur und Stabilität der Fehlerantwort 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 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 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, die Abdeckung im Laufe der Zeit für die Fehler zu erweitern, bei denen mehr Kontext erforderlich ist.
  • Other dynamic fields: 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. Sie sollten sich auf dieses Feld für die Logik des Kontrollflusses Ihrer Anwendung verlassen.

  • 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 ist, 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

Mit diesen Best Practices sorgen Sie dafür, dass 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, VARIABLE_NAME.

Exponentiellen Backoff implementieren

Bei Fehlern, die auf eine vorübergehende Nichtverfügbarkeit oder 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 gibt an, 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
2. Der API-Methodenname
3. Die Anfragenutzlast
4. Zeitstempel oder der Zeitraum, in dem die Methode aufgerufen und Fehler empfangen wurden