Fehlercodes
Wenn eine Anfrage fehlschlägt, prüfe den Fehlercode in der Antwort. Klappe ihn in der Liste unten auf, um zu erfahren, was passiert ist und wie du weiter vorgehst. Zu jedem Fehler findest du auch eine Beispielantwort und Hinweise zum Wiederholen der Anfrage.
400request.malformedDie Anfrage kann nicht eingelesen werden.
- Vorgehensweise
- JSON-Syntax, URL-Kodierung und Anfragestruktur prüfen.
- Wiederholungsregeln
- Erst nach Korrektur der Anfrage erneut versuchen.
{
"error": {
"code": "request.malformed",
"fields": null,
"message": "The request could not be read."
},
"meta": {
"request_id": "example-request"
}
}
401authentication.invalid_credentialsAPI-Schlüssel oder Zugriffstoken sind ungültig, abgelaufen oder widerrufen.
- Vorgehensweise
- Shop-URL und Zugangsdaten prüfen. Mit einem aktiven API-Schlüssel einen neuen Token anfordern.
- Wiederholungsregeln
- Erst nach Korrektur der Authentifizierung erneut versuchen; wiederholte ungültige Token-Anfragen vermeiden.
{
"error": {
"code": "authentication.invalid_credentials",
"fields": null,
"message": "The credentials are invalid."
},
"meta": {
"request_id": "example-request"
}
}
401authentication.requiredDer erforderliche Authorization-Header fehlt oder verwendet das falsche Schema.
- Vorgehensweise
- Verwende zum Ausstellen und Widerrufen eines Tokens deinen API-Schlüssel mit
ApiKeyim HeaderAuthorization. Verwende bei anderen Anfragen das Zugriffstoken mitBearer. - Wiederholungsregeln
- Erst nach Korrektur der Authentifizierung erneut versuchen; wiederholte ungültige Token-Anfragen vermeiden.
{
"error": {
"code": "authentication.required",
"fields": null,
"message": "Authentication is required."
},
"meta": {
"request_id": "example-request"
}
}
403authorization.client_ip_unverifiedDie Quell-IP-Adresse konnte nicht vertrauenswürdig bestimmt werden.
- Vorgehensweise
- Prüfe, über welche IP-Adresse deine Integration auf die API zugreift. Falls der Fehler weiterhin auftritt, wende dich an den technischen Support von Shopently.
- Wiederholungsregeln
- Wiederhole die Anfrage, nachdem das Problem bei der Erkennung der IP-Adresse geklärt wurde.
{
"error": {
"code": "authorization.client_ip_unverified",
"fields": null,
"message": "The client IP address could not be verified."
},
"meta": {
"request_id": "example-request"
}
}
403authorization.ip_not_allowedDie Quell-IP-Adresse steht nicht auf der erlaubten Adressliste des Schlüssels.
- Vorgehensweise
- Eine zugelassene Quelladresse verwenden oder einen berechtigten Administrator um Anpassung der IP-Liste bitten.
- Wiederholungsregeln
- Erst erneut versuchen, wenn die erforderlichen Zugriffsrechte wirksam sind.
{
"error": {
"code": "authorization.ip_not_allowed",
"fields": null,
"message": "Access from this IP address is not allowed."
},
"meta": {
"request_id": "example-request"
}
}
403authorization.scope_deniedDem Schlüssel fehlt eine wirksame Berechtigung für diese Operation.
- Vorgehensweise
- Erforderliche und bedingte Berechtigungen, Schlüsselrechte und Zugriff des Ausstellers prüfen.
- Wiederholungsregeln
- Erst erneut versuchen, wenn die erforderlichen Zugriffsrechte wirksam sind.
{
"error": {
"code": "authorization.scope_denied",
"fields": null,
"message": "The required permission has not been granted."
},
"meta": {
"request_id": "example-request"
}
}
403entitlements.api_disabledDer API-Zugriff ist für diesen Shop deaktiviert.
- Vorgehensweise
- Den Inhaber den aktiven Tarif und die API-Verfügbarkeit prüfen lassen.
- Wiederholungsregeln
- Erst erneut versuchen, wenn die erforderlichen Zugriffsrechte wirksam sind.
{
"error": {
"code": "entitlements.api_disabled",
"fields": null,
"message": "API access is disabled for this store."
},
"meta": {
"request_id": "example-request"
}
}
403entitlements.limit_exceededDie Änderung würde ein Limit des aktuellen Tarifs überschreiten.
- Vorgehensweise
- Das Ressourcenlimit prüfen und die geplante Änderung oder den Tarif anpassen. Für einen geänderten Schreibvorgang einen neuen Idempotency-Key verwenden.
- Wiederholungsregeln
- Erst nach Korrektur der Anfrage erneut versuchen.
{
"error": {
"code": "entitlements.limit_exceeded",
"fields": null,
"message": "The operation exceeds a plan limit."
},
"meta": {
"request_id": "example-request"
}
}
403entitlements.operation_disabledDer aktuelle Tarif enthält diese Operation nicht.
- Vorgehensweise
- Den bei der Operation angegebenen Mindesttarif und die Schlüsselberechtigungen prüfen.
- Wiederholungsregeln
- Erst erneut versuchen, wenn die erforderlichen Zugriffsrechte wirksam sind.
{
"error": {
"code": "entitlements.operation_disabled",
"fields": null,
"message": "The current plan does not allow this operation."
},
"meta": {
"request_id": "example-request"
}
}
403entitlements.resource_blockedEin Tariflimit sperrt diese Ressource.
- Vorgehensweise
- Den Inhaber die tarifbedingte Ressourcensperre auflösen lassen.
- Wiederholungsregeln
- Erst erneut versuchen, wenn die erforderlichen Zugriffsrechte wirksam sind.
{
"error": {
"code": "entitlements.resource_blocked",
"fields": null,
"message": "A plan limit blocks access to this resource."
},
"meta": {
"request_id": "example-request"
}
}
404resource.not_foundDie Ressource fehlt, wurde gelöscht oder ist unter dieser Kennung nicht verfügbar.
- Vorgehensweise
- Shop, Ressourcenpfad und Kennung prüfen. Von diesem Shop zurückgegebene Kennungen verwenden.
- Wiederholungsregeln
- Erst nach Korrektur der Anfrage erneut versuchen.
{
"error": {
"code": "resource.not_found",
"fields": null,
"message": "The resource was not found."
},
"meta": {
"request_id": "example-request"
}
}
405request.method_not_allowedDieser Endpunkt unterstützt die HTTP-Methode nicht.
- Vorgehensweise
- Die dokumentierte Methode verwenden. Der Allow-Header nennt die unterstützten Methoden.
- Wiederholungsregeln
- Erst nach Korrektur der Anfrage erneut versuchen.
{
"error": {
"code": "request.method_not_allowed",
"fields": null,
"message": "This method is not supported for this resource."
},
"meta": {
"request_id": "example-request"
}
}
409idempotency.key_reusedDieser Idempotency-Key gehört zu einer anderen Anfrage.
- Vorgehensweise
- Den ursprünglichen Vorgang ermitteln. Einen neuen Schlüssel nur für einen bewusst neuen logischen Vorgang verwenden.
- Wiederholungsregeln
- Die widersprüchliche Änderung nicht automatisch erzwingen oder wiederholt senden.
{
"error": {
"code": "idempotency.key_reused",
"fields": null,
"message": "This idempotency key was used with a different request."
},
"meta": {
"request_id": "example-request"
}
}
409resource.already_existsEin eindeutiger Wert kollidiert mit einer vorhandenen Ressource.
- Vorgehensweise
- Die vorhandene Ressource lesen und entscheiden, ob sie verwendet oder ein anderer eindeutiger Wert gewählt werden soll.
- Wiederholungsregeln
- Die widersprüchliche Änderung nicht automatisch erzwingen oder wiederholt senden.
{
"error": {
"code": "resource.already_exists",
"fields": null,
"message": "A resource with these unique values already exists."
},
"meta": {
"request_id": "example-request"
}
}
409resource.in_useAndere Ressourcen verwenden diese Ressource weiterhin.
- Vorgehensweise
- Die Abhängigkeiten prüfen und vor dem Löschen über unterstützte Operationen ändern oder entfernen.
- Wiederholungsregeln
- Erst nach Auflösung der Abhängigkeiten erneut versuchen.
{
"error": {
"code": "resource.in_use",
"fields": null,
"message": "The resource is still in use."
},
"meta": {
"request_id": "example-request"
}
}
409resource.state_conflictDer aktuelle Geschäftsstatus verhindert die Änderung.
- Vorgehensweise
- Den aktuellen Zustand lesen und einen zulässigen Zustandswechsel wählen.
- Wiederholungsregeln
- Die widersprüchliche Änderung nicht automatisch erzwingen oder wiederholt senden.
{
"error": {
"code": "resource.state_conflict",
"fields": null,
"message": "The current resource state does not allow this operation."
},
"meta": {
"request_id": "example-request"
}
}
409resource.version_conflictEin anderer Schreibvorgang hat die Ressource seit dem Lesen geändert.
- Vorgehensweise
- Den neuesten Zustand lesen, die Änderung abstimmen und die neue expected_version übermitteln.
- Wiederholungsregeln
- Für den abgestimmten neuen Vorgang einen neuen Idempotency-Key verwenden; Daten nicht ungeprüft überschreiben.
{
"error": {
"code": "resource.version_conflict",
"fields": null,
"message": "The resource version has changed."
},
"meta": {
"request_id": "example-request"
}
}
409storage.limit_reachedDas Speicherlimit für hochgeladene Bilder und Dateien ist erreicht. Geben Sie Speicher frei oder erhöhen Sie das Limit.
- Vorgehensweise
- Das Speicherlimit für hochgeladene Bilder und Dateien ist erreicht. Geben Sie Speicher frei oder erhöhen Sie das Limit.
- Wiederholungsregeln
- Kleinere, gültige Vorgänge mit jeweils eigenem Idempotency-Key übermitteln.
{
"error": {
"code": "storage.limit_reached",
"fields": null,
"message": "The upload storage limit is reached."
},
"meta": {
"request_id": "example-request"
}
}
413request.too_largeDie Anfrage überschreitet die Größenbegrenzung.
- Vorgehensweise
- Den Inhalt verkleinern oder die Arbeit in unterstützte Einzelvorgänge aufteilen.
- Wiederholungsregeln
- Kleinere, gültige Vorgänge mit jeweils eigenem Idempotency-Key übermitteln.
{
"error": {
"code": "request.too_large",
"fields": null,
"message": "The request exceeds the size limit."
},
"meta": {
"request_id": "example-request"
}
}
415request.unsupported_media_typeInhaltstyp oder Inhaltskodierung werden nicht unterstützt.
- Vorgehensweise
- Für JSON-Schreibvorgänge Content-Type: application/json und einen unterstützten unkomprimierten Inhalt verwenden.
- Wiederholungsregeln
- Erst nach Korrektur der Anfrage erneut versuchen.
{
"error": {
"code": "request.unsupported_media_type",
"fields": null,
"message": "The request media type or encoding is not supported."
},
"meta": {
"request_id": "example-request"
}
}
416request.range_not_satisfiableEinschränkungen: Range
- Vorgehensweise
- Range: bytes=0-(size_bytes-1)
- Wiederholungsregeln
- Erst nach Korrektur der Anfrage erneut versuchen.
{
"error": {
"code": "request.range_not_satisfiable",
"fields": null,
"message": "The requested byte range is unavailable."
},
"meta": {
"request_id": "example-request"
}
}
422request.validation_failedMindestens ein Feld oder Parameter besteht die Validierung nicht.
- Vorgehensweise
- error.fields sowie Pflichtfelder, null-Zulässigkeit, Kennungen und erlaubte Werte prüfen. Ein geänderter Schreibvorgang ist ein neuer logischer Vorgang.
- Wiederholungsregeln
- Erst nach Korrektur der Anfrage erneut versuchen.
{
"error": {
"code": "request.validation_failed",
"fields": null,
"message": "Some request parameters are invalid."
},
"meta": {
"request_id": "example-request"
}
}
429capacity.queue_fullDie kurze API-Warteschlange ist voll; die Ausführung der Anfrage hat nicht begonnen.
- Vorgehensweise
- Anfragen in eine Warteschlange stellen und den Antwortheader Retry-After beachten.
- Wiederholungsregeln
- Warte mindestens die in
Retry-Afterangegebene Anzahl an Sekunden. Behalte beim Wiederholen eines Schreibvorgangs denselben Anfrageinhalt und denselben Wert fürIdempotency-Keybei.
{
"error": {
"code": "capacity.queue_full",
"fields": null,
"message": "The API is busy. Please retry shortly."
},
"meta": {
"request_id": "example-request"
}
}
429capacity.wait_timeoutDie Wartezeit in der API-Warteschlange ist abgelaufen; die Ausführung hat nicht begonnen.
- Vorgehensweise
- Anfragen in eine Warteschlange stellen und den Antwortheader Retry-After beachten.
- Wiederholungsregeln
- Warte mindestens die in
Retry-Afterangegebene Anzahl an Sekunden. Behalte beim Wiederholen eines Schreibvorgangs denselben Anfrageinhalt und denselben Wert fürIdempotency-Keybei.
{
"error": {
"code": "capacity.wait_timeout",
"fields": null,
"message": "The API could not start this request in time. Please retry shortly."
},
"meta": {
"request_id": "example-request"
}
}
429rate_limit.exceededDie Anfragerate überschreitet das geltende Limit.
- Vorgehensweise
- Anfragen in eine Warteschlange stellen und den Antwortheader Retry-After beachten.
- Wiederholungsregeln
- Warte mindestens die in
Retry-Afterangegebene Anzahl an Sekunden. Behalte beim Wiederholen eines Schreibvorgangs denselben Anfrageinhalt und denselben Wert fürIdempotency-Keybei.
{
"error": {
"code": "rate_limit.exceeded",
"fields": null,
"message": "The request rate limit has been exceeded."
},
"meta": {
"request_id": "example-request"
}
}
500internal.errorEin unerwarteter Dienstfehler ist aufgetreten.
- Vorgehensweise
- Warte einen Moment, bevor du die Anfrage wiederholst. Tritt Fehler 500 erneut auf, wende dich an den technischen Support von Shopently. Gib in deiner Nachricht die Anfrage-ID an.
- Wiederholungsregeln
- Den Datenabruf kannst du nach einer kurzen Pause wiederholen. Verwende beim Wiederholen eines Schreibvorgangs denselben Wert für
Idempotency-Keyund ändere den Anfrageinhalt nicht.
{
"error": {
"code": "internal.error",
"fields": null,
"message": "An unexpected error occurred."
},
"meta": {
"request_id": "example-request"
}
}
502gateway.bad_responseDas Gateway hat keine gültige API-Antwort erhalten.
- Vorgehensweise
- Die Anfragekennung aufbewahren. Eine fehlgeschlagene Antwort beweist nicht, dass der Schreibvorgang unterblieben ist.
- Wiederholungsregeln
- Begrenzt mit zunehmender, zufällig variierter Wartezeit wiederholen. Bei demselben Schreibvorgang den ursprünglichen Idempotency-Key und unveränderten Inhalt beibehalten.
{
"error": {
"code": "gateway.bad_response",
"fields": null,
"message": "The API gateway could not obtain a valid response."
},
"meta": {
"request_id": "example-request"
}
}
504gateway.timeoutDie Wartezeit des Gateways auf die API ist abgelaufen.
- Vorgehensweise
- Wenn die Anfrage Daten geändert hat, prüfe, ob sie im Shop gespeichert wurden. Eine fehlende Antwort bedeutet nicht, dass der Schreibvorgang fehlgeschlagen ist. Tritt der Fehler wiederholt auf, wende dich mit der Anfrage-ID an den technischen Support von Shopently.
- Wiederholungsregeln
- Den Datenabruf kannst du nach einer kurzen Pause wiederholen. Verwende beim Wiederholen eines Schreibvorgangs denselben Wert für
Idempotency-Keyund ändere den Anfrageinhalt nicht.
{
"error": {
"code": "gateway.timeout",
"fields": null,
"message": "The API gateway timed out."
},
"meta": {
"request_id": "example-request"
}
}