Fehlercodes
HTTP-Statuscodes der Listings API, SYxxxxx-Fehlercodes für Listings und Social und die drei Fehlerantwortformate, die die v4 API zurückgibt.
Die Listings API verwendet übliche HTTP-Statuscodes, um das Ergebnis einer Anfrage mitzuteilen. Fehlercodes haben das Präfix SY und werden in der Fehlerzeichenfolge message im Format SYxxxxx: <human-readable reason> übermittelt.
HTTP-Statuscodes
HTTP status code summary
Drei Antwortstrukturen
Die meisten Fehler enthalten ein Array errors, entweder auf der obersten Ebene oder verschachtelt im Ergebnis der Operation, wie die folgenden Abschnitte zeigen. Einige Fehler geben stattdessen ein einzelnes Objekt error zurück: überschrittene Anfragelimits (429) und einige Fehler auf Anfrageebene (400/500 mit einem code wie INTERNAL_SERVER_ERROR). Prüfen Sie beide Fälle: errors ist ein Array, error ist ein Objekt.
1. Anfrageebene: errors[] auf der obersten Ebene
Authentifizierungs- und Autorisierungsfehler sowie fehlerhafte Anfragen führen zum Abbruch, bevor die Operation ausgeführt wird. Dabei wird der entsprechende Status 4xx (siehe oben) mit dem Fehler auf der obersten Ebene der Antwort zurückgegeben.
{ "data": { "createLocation": null }, "errors": [{ "message": "SY90005: Invalid Token" }]}2. Schreibvalidierung: verschachteltes data.<operation>.errors[]
Eine ansonsten korrekt aufgebaute Anfrage zum Erstellen, Aktualisieren oder Veröffentlichen gibt HTTP 200 zurück. Verstößt die Eingabe gegen eine Geschäftsregel, wird der Fehler verschachtelt in den Nutzdaten der jeweiligen Operation unter data.<operation>.errors gemeldet. Bei Erfolg ist dieses Array vorhanden und leer ("errors": []).
{ "data": { "createLocation": { "errors": [ { "message": "SY10126: City is Mandatory" }, { "message": "SY10010: state_iso" } ], "location": null } }}3. Gateway-Ebene: ein einzelnes Objekt error auf der obersten Ebene
Überschrittene Anfragelimits und unerwartete Gateway-Fehler führen vor der Übersetzung zum Abbruch und geben ein Objekt error mit einem code, einem message und einem correlation_id zurück. Den Antwortinhalt für 429 finden Sie weiter unten unter rate_limited.
Lesen Sie bei einem Schreibvorgang immer data.<operation>.errors, auch bei einem 200 mit einem gefüllten Objekt data.<operation>: Ein Schreibvorgang kann teilweise fehlschlagen und dies hier melden.
Eine 402 Payment Required-Antwort hat keine error-Umhüllung: code, message, doc_url und, wenn eine Rechnung zu bezahlen ist, pay_url befinden sich auf der obersten Ebene. Siehe payment_required weiter unten.
Das Wiederholen eines Schreibvorgangs kann Folgen haben
Die v4-API unterstützt Idempotency-Key nicht: Der Header wird ignoriert, und kein Endpunkt erkennt wiederholte Schreibvorgänge. Ein Aufruf zum Erstellen, Aktualisieren oder Veröffentlichen, bei dem eine Zeitüberschreitung auftritt oder der einen 5xx zurückgibt, kann auf dem Server dennoch bereits gespeichert worden sein. Eine ungeprüfte Wiederholung kann daher einen doppelten Standort, Beitrag oder eine doppelte Antwort auf eine Bewertung erzeugen.
Lesevorgänge können Sie mit zunehmender Wartezeit zwischen den Versuchen bedenkenlos wiederholen. Lesen Sie bei einem Schreibvorgang zuerst den gespeicherten Stand aus: Suchen Sie den Datensatz anhand eines Schlüssels, den Sie kontrollieren (storeId, ein Filialcode, die Antwortliste der Interaktion), und wiederholen Sie den Aufruf nur, wenn der Datensatz tatsächlich fehlt.
Häufige Codes
Common SY error codes
Validierungscodes im Bereich SY10xxx beziehen sich auf ein bestimmtes Eingabefeld; message nennt das Feld oder die Regel, deren Prüfung fehlgeschlagen ist. Authentifizierungs- und Autorisierungscodes im Bereich SY90xxx gelten für die gesamte Anfrage und werden auf der obersten Ebene mit dem entsprechenden Status zurückgegeben.
Codes für verbundene Konten
Codes im Bereich SY810xx stammen von den Connected Accounts-Endpunkten, die einen Eintrag auf einer Plattform importieren oder verknüpfen. Sie werden bei HTTP 200 verschachtelt im Antworttext zurückgegeben (Antwortstruktur 2 oben). Lesen Sie daher data.<operation>.errors auch dann aus, wenn der Status einen Erfolg anzeigt.
SY810xx connected-account and import codes
Social-Codes
Codes im Bereich SY950xx stammen von den Social-Endpunkten für Marken, Verbindungen und Social-Beiträge. Wie die Codes für verbundene Konten werden sie bei einem HTTP 200 verschachtelt im Antworttext zurückgegeben. Lesen Sie daher data.<operation>.error (und data.<operation>.errors bei den Routen für Massenoperationen), auch wenn der Status einen Erfolg anzeigt.
SY950xx Social codes
SY95042 und SY95044 sind Fehler aufgrund fehlender Tarifberechtigungen, keine Eingabefehler: Ein erneuter Versuch ohne Tarifänderung schlägt auf dieselbe Weise fehl. SY95045, SY95046, SY95049 und SY95052 sind Eingabefehler, die sich in der nächsten Anfrage beheben lassen.
Codes für Listings-Berechtigungen
Listings plan codes
Codes für Listings scan
Codes im Bereich SY830xx stammen von den Endpunkten für listings scan. Wenn ein Scan nicht erstellt werden kann, wird der Fehler bei einem HTTP 200 verschachtelt im Antworttext zurückgegeben: Lesen Sie data.createListingScan.errors und prüfen Sie, ob scan den Wert null hat. SY83005 ist die Ausnahme: Beim Lesen eines nicht vorhandenen Scans wird 404 zurückgegeben.
SY830xx listings scan codes
Bei einem Aufruf des Endpunkts zum Erstellen mit einem schreibgeschützten Schlüssel wird stattdessen SY90016 zurückgegeben, ein HTTP 400. SY83001, SY83002 und SY83004 ändern sich nicht, wenn Sie dieselbe Anfrage sofort wiederholen, während sich bei SY83010 ein erneuter Versuch nach einer Pause lohnt.
rate_limited
429 Too Many Requests: Das Konto hat das Anfragelimit seines Tarifs überschritten. Der Antworttext enthält die standardmäßige Fehlerantwort mit einem retry_after_seconds-Hinweis, einem correlation_id zur Angabe in Supportanfragen und einem doc_url, das auf diesen Abschnitt verweist:
{ "error": { "code": "RATE_LIMITED", "message": "Too many requests. Slow down.", "retry_after_seconds": 30, "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c", "doc_url": "https://listingsapi.com/docs/error-codes#rate_limited" }}Warten Sie entsprechend retry_after_seconds (oder dem Header Retry-After, falls vorhanden) und versuchen Sie es dann mit exponentiell steigenden Wartezeiten erneut. Unter Anfragelimits finden Sie die Limits pro Tarif und eine Referenzimplementierung für dieses Wiederholungsverfahren.
payment_required
402: Die letzte Zahlung für dieses Konto ist fehlgeschlagen, daher sind alle /api/v4-Endpunkte ausgesetzt. Der Antworttext enthält pay_url, die Stripe-Seite für die unbezahlte Rechnung, sofern eine solche Seite verfügbar ist, und der Antwortheader X-Error-Code enthält dieselbe code. Sie können weiterhin die Abrechnungsseite im Dashboard öffnen, um die Zahlung vorzunehmen.
{ "code": "payment_required", "message": "This account has an unpaid invoice, so API access is paused. Pay the invoice to restore access.", "pay_url": "https://invoice.stripe.com/i/acct_123/test_abc", "doc_url": "https://listingsapi.com/docs/error-codes#payment_required"}Der Zugriff wird innerhalb einer Minute nach Bezahlung der letzten offenen Rechnung wiederhergestellt. Wenn die Rechnung 3 Tage nach der ersten fehlgeschlagenen Zahlung noch unbezahlt ist, wird das Listings-Abonnement gekündigt und die Standorte des Kontos werden archiviert. Wenn das Konto auch ein aktives Social-Abonnement hat, behält es den Zugriff auf Social; andernfalls wird das Konto geschlossen und seine API-Schlüssel funktionieren nicht mehr.
social_payment_required
402: Die letzte Zahlung für das Social-Abonnement ist fehlgeschlagen, daher sind die Social-Endpunkte (/api/v4/social/*) ausgesetzt. Die Listings-Endpunkte funktionieren weiterhin. Der Antworttext enthält dieselben Felder wie payment_required, mit "code": "social_payment_required". Wenn die Rechnung 3 Tage nach der ersten fehlgeschlagenen Zahlung noch unbezahlt ist, wird das Social-Abonnement gekündigt und die Marken des Kontos werden archiviert. Ein Konto ohne Listings-Abonnement wird geschlossen, und seine API-Schlüssel funktionieren nicht mehr.
Fehler der Steuerungsebene im Entwicklerportal
Die Endpunkte zur Konto- und Schlüsselverwaltung im Entwicklerportal (die eigenen API-Routen des Dashboards) geben eine einheitliche, strukturierte Fehlerantwort zurück, die sich von den oben beschriebenen REST-errors[]-Formaten unterscheidet. Jedes code enthält ein correlation_id und ein doc_url, das auf den zugehörigen Abschnitt auf dieser Seite verweist.
{ "error": { "code": "AUTH_INVALID_KEY", "message": "Session is invalid or expired.", "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c", "doc_url": "https://listingsapi.com/docs/error-codes#auth_invalid_key" }}auth_missing_key
401: Es wurden keine Zugangsdaten angegeben. Melden Sie sich erneut an oder senden Sie Ihren Schlüssel als Authorization: API <your-key>.
auth_invalid_key
401: Die Sitzung oder der Schlüssel ist ungültig oder abgelaufen. Authentifizieren Sie sich erneut oder stellen Sie im Dashboard einen neuen Schlüssel aus.
auth_insufficient_scope
403: Die Zugangsdaten sind gültig, berechtigen jedoch nicht zu dieser Aktion. Ein Schlüssel mit Leseberechtigung kann keine Schreibendpunkte aufrufen; stellen Sie bei Bedarf einen Schlüssel mit Schreibberechtigung aus.
not_found
404: Die angeforderte Ressource oder eine über ihre ID adressierte Ressource existiert nicht.
conflict
409: Die Anfrage steht im Konflikt mit dem aktuellen Zustand der Ressource (zum Beispiel beim Widerrufen eines bereits widerrufenen Schlüssels).
validation_failed
422: Die Validierung des Anfrageinhalts ist fehlgeschlagen. field und details in der Antwort benennen die fehlerhafte Eingabe.
internal_error
500: Ein unerwarteter serverseitiger Fehler. Wiederholen Sie einen Lesevorgang mit exponentiell steigenden Wartezeiten; lesen Sie bei einem Schreibvorgang zuerst den Datensatz erneut aus (siehe Die Wiederholung eines Schreibvorgangs ist nicht kostenlos). Geben Sie correlation_id an, wenn Sie den Support kontaktieren.
dependency_unavailable
503: Ein Dienst, von dem die API abhängt, ist vorübergehend nicht verfügbar. Wiederholen Sie die Anfrage mit steigenden Wartezeiten.
Informationen zu 429 finden Sie oben unter rate_limited.
Fehler im Code behandeln
Prüfen Sie zuerst den HTTP-Status; durchsuchen Sie dann bei Schreibvorgängen den Antwortinhalt nach einem verschachtelten errors-Array:
from listingsapi import APIError, ListingsAPI client = ListingsAPI(api_key=os.environ["LISTINGSAPI_KEY"]) try: location = client.locations.create(input=payload)except APIError as e: # Raised for a non-2xx status (AuthenticationError, ValidationError, and # so on) and for an error payload returned inside a 200 body. raise RuntimeError(f"Listings API error: {e}") from eBei direkter Verwendung der HTTP-API führen Sie dieselben beiden Prüfungen explizit durch: zuerst die Prüfung des Statuscodes, dann die Prüfung der Antwortdaten:
resp = requests.post( "https://listingsapi.com/api/v4/locations", headers={"Authorization": f"API {os.environ['LISTINGSAPI_KEY']}"}, json=payload, timeout=30,)resp.raise_for_status()body = resp.json() op = (body.get("data") or {}).get("createLocation") or {}if op.get("errors"): messages = [e["message"] for e in op["errors"]] raise RuntimeError(f"Listings API error: {messages}")Das Python SDK übernimmt beides für Sie: Es ordnet jedem HTTP-Status eine typisierte Ausnahme zu und löst auch bei Fehlerdaten, die innerhalb eines 200-Antwortinhalts zurückgegeben werden, eine Ausnahme aus.