Fehlerantworten#

HTTP-Status	Bedeutung	Empfohlene Maßnahme
`400 Bad Request`	Der Anfragetext oder die Abfrageparameter sind ungültig.	Korrigieren Sie die Anfrage, bevor Sie es erneut versuchen.
`401 Unauthorized`	Anmeldeinformationen fehlen, sind ungültig, abgelaufen oder nicht aktiv.	Überprüfen Sie die Authentifizierungsheader oder wenden Sie sich an Ideal House.
`403 Forbidden`	Die angeforderte `shopId` ist nicht mit den Zugangsdaten verknüpft.	Verwenden Sie die den Zugangsdaten zugewiesene Shop ID.
`404 Not Found`	Es ist kein Importstatus oder passendes Produkt verfügbar.	Prüfen Sie die Shop ID und die angeforderte Produkt-ID oder SKU.
`409 Conflict`	Für den Shop ist bereits ein anderer Importauftrag aktiv.	Warten Sie, bis der aktuelle Importauftrag abgeschlossen ist.
`429 Too Many Requests`	Die Anfragerate ist zu hoch.	Wiederholen Sie den Versuch mit exponentiellem Backoff und Jitter.
`500 Internal Server Error`	Beim Dienst ist ein unerwarteter Fehler aufgetreten.	Versuchen Sie es erneut mit exponentiellem Backoff. Wenden Sie sich an Ideal House, wenn der Fehler weiterhin besteht.
`502 Bad Gateway` oder `503 Service Unavailable`	Die API ist vorübergehend nicht verfügbar.	Wiederholen Sie die Anfrage mit exponentiell wachsender Wartezeit.

Ein Validierungsfehler kann das folgende Format haben:

json

{
  "message": ["shopId should not be empty"],
  "error": "Bad Request",
  "statusCode": 400
}

Der Text in message kann variieren. Verwenden Sie den HTTP-Statuscode und dokumentierte Antwortfelder für die Programmlogik.

Anleitung zu Wiederholungsversuchen und Wiederherstellung#

Fragen Sie den Status alle 2 bis 5 Sekunden ab, solange der Auftrag den Status pending oder running hat.
Verwenden Sie bei Antworten mit 429, 500, 502 und 503 exponentiellen Backoff mit Jitter und legen Sie eine maximale Anzahl von Wiederholungsversuchen fest.
Wiederholen Sie Anfragen nach Antworten mit 400, 401 oder 403 nicht automatisch, ohne die Anfrage oder die Zugangsdaten zu korrigieren.
Warten Sie nach 409, bis der aktive Auftrag den Status completed oder failed erreicht.
Wenn bei einer Übermittlung eine Zeitüberschreitung auftritt, bevor Sie eine Antwort erhalten, fragen Sie den Statusendpunkt ab, bevor Sie den Stapel erneut übermitteln.
Der erneute Versuch desselben Produkts mit derselben SKU ist sicher, da Importe das Verhalten „Erstellen oder Aktualisieren“ verwenden.
Senden Sie nach einem abgeschlossenen Auftrag mit Fehlern auf Artikelebene einen neuen Stapel, der nur die fehlerhaften Produkte enthält.
Nach einem Fehler auf Auftragsebene können die in successCount gezählten Produkte bereits aktualisiert worden sein. Die ursprüngliche Charge kann mit denselben SKUs sicher erneut übermittelt werden.
Eine Löschung kann bereits erfolgt sein, auch wenn die Anfrage 503 zurückgibt. Dieselbe Löschanfrage kann sicher wiederholt werden.

Der Statusendpunkt dient zur Verfolgung des aktiven oder letzten Auftrags, nicht als dauerhafter Importverlauf. Speichern Sie die übermittelte Charge, jobId, Statusantworten und das Endergebnis zur Abstimmung und Unterstützung in Ihrem eigenen System.

Produktionscheckliste#

Speichern Sie den Client Secret in einem Secrets-Manager oder einer geschützten Serverumgebung.
Verwenden Sie für jedes Produkt eine stabile, eindeutige SKU.
Senden Sie nicht mehr als 500 Produkte pro Anfrage.
Stellen Sie sicher, dass Bild-URLs öffentlich erreichbar sind und während der Verarbeitung verfügbar bleiben.
Setzen Sie processImages: true nur ausdrücklich, wenn eine Bildvorverarbeitung benötigt wird und die Verarbeitungskosten von 1 Credit pro Bild akzeptiert werden. Andernfalls lassen Sie das Feld weg oder setzen Sie es auf false.
Aktivieren Sie die Aufteilung von Bodenbelagsbildern nur, indem Sie sowohl processImages als auch processFloorImages auf true setzen.
Geben Sie für jedes Produkt name, imageUrl, productUrl, width, height und einen unterstützten productType an.
Wenn Sie status angeben, setzen Sie das Feld auf active, inactive, out_of_stock oder invalid.
Senden Sie Abmessungen als positive Werte mit einer unterstützten Einheit oder ohne Einheit, um Zoll zu verwenden; gespeicherte Werte werden auf Zoll normiert.
Speichern Sie die zurückgegebene jobId dauerhaft und vergleichen Sie sie mit nachfolgenden Statusantworten.
Behandeln Sie completed mit failedCount > 0 als Teilerfolg.
Blättern Sie durch die Produktliste, anstatt einen unbegrenzten Katalog anzufordern.
Geben Sie beim Löschen genau einen Identifikator an: productId oder sku.
Implementieren Sie begrenzte Wiederholungsversuche mit exponentiellem Backoff und Jitter.

Für Anmeldeinformationen, Onboarding-Werte, Produkttypzuordnung oder anhaltende Integrationsprobleme wenden Sie sich an Ihren Ideal House-Integrationsvertreter.