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

StatusBedeutungTypischer SY-CodeAusnahme im Python SDK
200 OKAnfrage erfolgreich. Prüfen Sie bei Schreibvorgängen auch den Antwortinhalt (siehe unten).--
400 Bad RequestEine fehlerhafte Anfrage, ein nicht analysierbarer Filter, ein ungültiger Enum-Wert oder eine fehlerhafte ID.SY90006, SY90001ValidationError
401 UnauthorizedDer API-Schlüssel fehlt, ist fehlerhaft oder wurde widerrufen. Sie haben noch keinen Schlüssel? Holen Sie sich einen kostenlosen Sandbox-Tagespass, wenn dieser angeboten wird.SY90005AuthenticationError
402 Payment RequiredDas Konto hat eine unbezahlte Rechnung, daher ist der API-Zugriff ausgesetzt. Eine unbezahlte Rechnung, die nur Social betrifft, setzt nur die Social-Endpunkte aus. Siehe payment_required und social_payment_required.-APIError
403 ForbiddenDer Schlüssel ist gültig, berechtigt aber nicht zum Zugriff auf die Ressource.SY90003PermissionDeniedError
404 Not FoundDer Pfad oder eine über eine ID adressierte Ressource existiert nicht.SY90002NotFoundError
422 Unprocessable EntityDie Anfrage war korrekt aufgebaut, aber ein Wert konnte nicht verarbeitet werden (zum Beispiel eine unbekannte oder mehrdeutige Kategorie).-ValidationError
429 Too Many RequestsSie haben das Anfragelimit Ihres Tarifs überschritten. Beachten Sie den Header Retry-After.-RateLimitError
5xxEin Serverfehler. Ein Lesevorgang kann mit zunehmender Wartezeit zwischen den Versuchen bedenkenlos wiederholt werden; beachten Sie vor dem Wiederholen eines Schreibvorgangs den Hinweis weiter unten.SY90007InternalServerError

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.

JSON
{  "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": []).

JSON
{  "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

CodeMeldungHTTP-StatusBedeutung
SY90005Invalid Token401Der API-Schlüssel fehlt, ist fehlerhaft formatiert oder wurde widerrufen. Erstellen Sie im Dashboard einen neuen Schlüssel und senden Sie ihn als Authorization: API <your-key>.
SY90001Not authorized to access this resource401 / 403Der Schlüssel wurde für diese Ressource abgelehnt. Sowohl das Python SDK als auch das Node SDK lösen dafür AuthenticationError aus.
SY90002Invalid Id404 / 400Ein Pfad oder eine als Argument übergebene ID konnte nicht aufgelöst werden (häufig eine fehlerhafte oder nicht base64-kodierte Relay-ID).
SY10126City is Mandatory200 (Antworttext)Ein Pflichtfeld (city) wurde in der Eingabe ausgelassen.
SY10010state_iso200 (Antworttext)Der Wert für stateIso fehlt oder ist ungültig. Gültige Werte finden Sie über den Endpunkt für Länder und Bundesstaaten.
SY10050At least one service area place is required200 (Antworttext)serviceArea.businessType ist CUSTOMER_LOCATION_ONLY und placeInfos ist leer.
SY10051Region code is required for CUSTOMER_LOCATION_ONLY business type200 (Antworttext)serviceArea.regionCode fehlt. Senden Sie einen zweistelligen Ländercode wie US.
SY10052Address is required when business type is CUSTOMER_AND_BUSINESS_LOCATION200 (Antworttext)Der Standort hat weder street noch city. Senden Sie eines davon oder verwenden Sie CUSTOMER_LOCATION_ONLY.

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

CodeBedeutungVorgehen
SY81019Für das dem Schlüssel zugeordnete Konto konnte kein Benutzer ermittelt werden.Wenden Sie sich an den Support: Das Konto hat keinen aktiven Hauptbenutzer.
SY81066connectedAccountId existiert nicht oder das Konto ist archiviert.Lesen Sie die ID erneut aus GET /connected-accounts aus.
SY81067connectedAccountListingId konnte nicht dekodiert oder aufgelöst werden.Rufen Sie den Wert erneut aus id eines connected-account-listings-Datensatzes ab.
SY81068Dieser Eintrag ist bereits mit einem Standort verknüpft.Trennen Sie zunächst die Verknüpfung oder wählen Sie einen anderen Eintrag.
SY81069Die Zugangsdaten des verbundenen Kontos sind nicht mehr gültig.Verbinden Sie das Konto erneut über connect-google oder connect-facebook.
SY81070Der Eintrag gehört nicht zu dem von Ihnen angegebenen verbundenen Konto.Ordnen Sie jeden Eintrag dem Konto zu, aus dem er stammt. Eine häufige Ursache ist der Abruf von Einträgen ohne connectedAccountId im Anfragetext, wodurch die Einträge eines anderen Kontos zurückgegeben werden.
SY81071Beim Erstellen des Standorts ist ein unerwarteter Fehler aufgetreten.Versuchen Sie es erneut; falls der Fehler weiterhin auftritt, wenden Sie sich an den Support.
SY81072Das Erstellen des Standorts ist beim Zusammenstellen oder Speichern fehlgeschlagen.Versuchen Sie es erneut; falls der Fehler weiterhin auftritt, wenden Sie sich an den Support.
SY81073Dieser Eintragstyp wird für den Import nicht unterstützt.Es können nur Einträge von Google und Facebook importiert werden.
SY81074Google hat keine Daten für den Eintrag zurückgegeben.Prüfen Sie, ob der Eintrag noch existiert und weiterhin von dem Konto verwaltet wird.
SY81075Das Anfragelimit der Google-API wurde überschritten.Versuchen Sie es später mit zunehmenden Wartezeiten zwischen den Versuchen erneut.
SY81076Der Abruf des Eintrags von Google ist fehlgeschlagen.Versuchen Sie es erneut; prüfen Sie die Google-Berechtigungen des Kontos.
SY81077Das Land konnte nicht anhand der Facebook-Seite ermittelt werden.Ergänzen Sie das Land in der Adresse der Seite auf Facebook und versuchen Sie es dann erneut.
SY81078Das Zusammenstellen der Standortdaten anhand der Facebook-Seite ist fehlgeschlagen.Versuchen Sie es erneut; falls der Fehler weiterhin auftritt, wenden Sie sich an den Support.
SY81081Für den Eintrag ist keine Hauptkategorie festgelegt.Legen Sie eine Hauptkategorie für den Eintrag fest und versuchen Sie es dann erneut.
SY81082Das Land des Eintrags wird nicht unterstützt.Unterstützte Länder finden Sie über den Endpunkt für Länder und Bundesstaaten.
SY81083Der Google-Eintrag konnte nicht importiert werden.Wenden Sie sich unter Angabe des Zeitstempels an den Support.
SY81084Bei der Vorbereitung des Facebook-Imports ist ein interner Fehler aufgetreten.Versuchen Sie es erneut; falls der Fehler weiterhin auftritt, wenden Sie sich unter Angabe des Zeitstempels an den Support.
SY81085Die Facebook-Seite konnte nicht importiert werden.Wenden Sie sich unter Angabe des Zeitstempels an den Support.
SY81086Das Erstellen des Standorts wurde aufgrund einer Geschäftsregel abgelehnt. Das verschachtelte Feld message enthält den zugrunde liegenden Code, beispielsweise SY10151, wenn das Konto keine freien Standortplätze mehr hat.Lesen Sie die verschachtelte Meldung; buchen Sie bei SY10151 eine Standorterweiterung hinzu oder wechseln Sie zu einem höheren Tarif.
SY81087Die Anfrage zum Erstellen des Standorts ist fehlgeschlagen.Versuchen Sie es erneut; falls der Fehler weiterhin auftritt, wenden Sie sich unter Angabe des Zeitstempels an den Support.
SY81088Das Erstellen des Standorts ist aus einem unbekannten Grund fehlgeschlagen.Wenden Sie sich unter Angabe des Zeitstempels an den Support.
SY81089Ein interner Dienstaufruf hat einen Status zurückgegeben, der keinen Erfolg anzeigt. Das Problem liegt nicht an Ihrer Anfrage.Versuchen Sie es einmal erneut; falls der Fehler weiterhin auftritt, wenden Sie sich unter Angabe des Zeitstempels an den Support, damit wir den internen Aufruf nachverfolgen können.
SY81090Beim internen Aufruf zum Erstellen des Standorts ist ein unerwarteter Fehler aufgetreten.Versuchen Sie es erneut; falls der Fehler weiterhin auftritt, wenden Sie sich unter Angabe des Zeitstempels an den Support.

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

CodeBedeutungVorgehen
SY95041Das Konto hat sein Markenlimit erreicht. Kann bei einem API-Tarif nicht auftreten: Dort ist die Anzahl der Marken unbegrenzt.Bei einem API-Tarif ist keine Aktion erforderlich. Falls dieser Code dennoch auftritt, melden Sie ihn: GET /social/limits sollte brands: null zurückgeben.
SY95042Das Konto hat sein Verbindungslimit für den aktuellen Abrechnungszeitraum erreicht.Die Obergrenze wird mit usage.connections aus GET /social/limits verglichen. Das ist die abrechenbare Anzahl: aktuell verbundene Konten zuzüglich der in diesem Zeitraum freigegebenen Konten. Ein durch Trennen einer Verbindung oder Archivieren einer Marke freigegebener Platz bleibt bis zum Ende des Zeitraums reserviert. Daher behebt eine kürzlich getrennte Verbindung diesen Fehler nicht. Verbinden Sie eines der freigegebenen Konten erneut mit seiner bisherigen Marke (kostenlos, da derselbe Platz wiederverwendet wird), kaufen Sie ein weiteres Paket mit 5 Verbindungen (sofort verfügbar) oder warten Sie auf die Verlängerung, bei der usage.connectionsReleased Plätze wieder verfügbar werden. Wenn Sie ein freigegebenes Konto mit einer anderen Marke verbinden, wird der Platz nicht wiederverwendet. Siehe Tarife und Zusatzpakete.
SY95043In diesem Konto gibt es keine Marke mit dieser ID, oder die Marke ist archiviert.Lesen Sie die ID erneut aus GET /social/brands aus. Marken-IDs sind einfache UUIDs, keine Base64-Relay-IDs.
SY95044Diese Plattform ist für dieses Konto nicht aktiviert.Der Social-Tarif des Kontos umfasst die Plattform nicht, mit der Sie eine Verbindung herstellen möchten. Wenden Sie sich an den Support oder wählen Sie eine Plattform, die für das Konto verfügbar ist.
SY95045Die Marke hat keinen verbundenen Kanal für diese Plattform.Leiten Sie den Benutzer über einen Verbindungslink für diese Plattform weiter oder entfernen Sie die Plattform aus platforms. Dieser Code tritt auch auf, wenn die Verbindung zum Kanal nach der Planung des Beitrags getrennt wurde.
SY95046Der geplante Zeitpunkt oder die Zeitzone ist ungültig.Senden Sie scheduledAt oder scheduleDate + scheduleTime, niemals beides. scheduledAt benötigt einen UTC-Offset; scheduleTime ist HH:MM. Zeitzonen werden als IANA-Kennungen angegeben (tzCode).
SY95047In diesem Konto gibt es keinen Massenauftrag mit dieser ID.Lesen Sie job.id erneut aus der Antwort auf die Massenerstellung aus. Aufträge werden nicht unbegrenzt aufbewahrt.
SY95048Die Massenanfrage überschreitet das Zeilenlimit.Senden Sie höchstens 500 Zeilen pro Anfrage und teilen Sie die übrigen Zeilen auf weitere Stapel auf. Es wurde nichts erstellt.
SY95049Die Weiterleitungs-URL ist ungültig.redirectUrl und errorUrl bei einem Verbindungslink müssen absolute https-URLs sein, die Sie kontrollieren.
SY95050Die Validierung der Massenanfrage ist fehlgeschlagen; siehe die Fehler pro Zeile.Es wurde nichts erstellt. Lesen Sie job.results[]: Jede abgelehnte Zeile enthält ihren bei 0 beginnenden index, ihren clientReference und den Grund in errors[]. Korrigieren Sie diese Zeilen und senden Sie den gesamten Stapel erneut.
SY95051Die Marke erfüllt die Anforderung eines Mindestalters von 90 Tagen noch nicht.Eine Marke kann erst archiviert werden, wenn sie 90 Tage alt ist. Die Antwort enthält außerdem status: "TENURE_NOT_MET", und es wurde nichts geändert. Versuchen Sie es nach dem 90. Tag erneut. Dann werden die Marke und ihre Verbindungen sofort archiviert; ihre Verbindungsplätze bleiben jedoch bis zum Ende des Abrechnungszeitraums reserviert. Siehe die Regel zum Mindestalter.
SY95052Der verbundene Kanal gehört nicht zu dieser Marke.Ordnen Sie jede Verbindung der Marke zu, für die sie erstellt wurde. Dieser Fehler tritt häufig auf, wenn für einen Insights-Aufruf der Beitrag einer Marke und die Kanal-ID einer anderen Marke verwendet werden.

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

CodeBedeutungMaßnahme
SY10150Das Konto hat sein Standortlimit erreicht.Archivieren Sie einen Standort, kaufen Sie eine Erweiterung für einen zusätzlichen Standort oder wechseln Sie zu einem höheren Tarif. Siehe Tarife und Erweiterungen.
SY10151Für das Konto sind in diesem Tarif keine freien Standortplätze mehr verfügbar. Bei einem Sandbox-Tagespass werden beide verfügbaren Standorte bereits genutzt.Es gelten dieselben Maßnahmen wie bei SY10150. Aktualisieren Sie bei einem Tagespass einen vorhandenen Standort oder wählen Sie einen kostenpflichtigen Tarif. Dieser Code tritt auch verschachtelt in SY81086 auf, wenn ein Standort aus einem Eintrag eines verbundenen Kontos erstellt wird.
SY10152Der Standort ist noch nicht lange genug aktiv, um archiviert werden zu können.Standorte müssen für die Mindestdauer des Kontos, standardmäßig 90 Tage, aktiv sein, bevor POST /locations/archive sie akzeptiert. Warten Sie, bis diese Dauer abgelaufen ist.
SY10155Das Konto hat keinen Listings-Tarif, daher können keine Standorte erstellt werden.Der API-Schlüssel gehört zu einem Konto ohne Listings-Abonnement, beispielsweise einem Konto, das nur Social nutzt. Standorte gehören zum Produkt Listings; schließen Sie ein Abonnement dafür ab, bevor Sie POST /locations aufrufen.

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

CodeBedeutungMaßnahme
SY83001Listing scans sind in Ihrem Tarif nicht verfügbar.Listings scans sind in kostenpflichtigen Tarifen enthalten und mit einem Sandbox-Tagespass nicht verfügbar. Verwenden Sie ein Konto mit einem kostenpflichtigen Tarif. Siehe Tarife und Erweiterungen.
SY83002Das monatliche Kontingent für den listing scan ist aufgebraucht. Die Meldung enthält das Limit und den Zeitpunkt der Zurücksetzung, und quota wird zurückgegeben.Warten Sie bis quota.resetsAt oder kontaktieren Sie uns wegen eines höheren Kontingents. Das Wiederholen eines Scans aus den letzten 7 Tagen verbraucht kein Kontingent und funktioniert weiterhin.
SY83003Ungültiger Wert für ein Feld. contextInfo nennt das Feld unter field.Korrigieren Sie dieses Feld und senden Sie die Anfrage erneut. phone erfordert 6 bis 15 Ziffern, countryIso zwei Buchstaben, und stateIso sowie postalCode sind in den meisten Ländern erforderlich.
SY83004Listing scans sind für dieses Land nicht verfügbar.Prüfen Sie countryIso. Die Meldung nennt den abgelehnten Code.
SY83005Listing scan nicht gefunden. Wird als HTTP 404 zurückgegeben.Die ID ist unbekannt, gehört zu einem anderen Konto oder der Scan ist älter als 90 Tage und wurde entfernt. Lesen Sie die ID aus GET /listings/scans.
SY83010Listing scans sind vorübergehend nicht verfügbar. Dieser Code wird auch als failure-Code bei einem Scan zurückgegeben, der nicht gestartet werden konnte.Versuchen Sie es später erneut. Ein fehlgeschlagener Scan verbraucht kein Kontingent.

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:

JSON
{  "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.

JSON
{  "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.

JSON
{  "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:

Python
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 e

Bei 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:

Python
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.