Zum Inhalt springen
ShopentlyLearn

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.
Antwort
{
  "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.
Antwort
{
  "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 ApiKey im Header Authorization. Verwende bei anderen Anfragen das Zugriffstoken mit Bearer.
Wiederholungsregeln
Erst nach Korrektur der Authentifizierung erneut versuchen; wiederholte ungültige Token-Anfragen vermeiden.
Antwort
{
  "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.
Antwort
{
  "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.
Antwort
{
  "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.
Antwort
{
  "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.
Antwort
{
  "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.
Antwort
{
  "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.
Antwort
{
  "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.
Antwort
{
  "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.
Antwort
{
  "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.
Antwort
{
  "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.
Antwort
{
  "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.
Antwort
{
  "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.
Antwort
{
  "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.
Antwort
{
  "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.
Antwort
{
  "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.
Antwort
{
  "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.
Antwort
{
  "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.
Antwort
{
  "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.
Antwort
{
  "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.
Antwort
{
  "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-After angegebene Anzahl an Sekunden. Behalte beim Wiederholen eines Schreibvorgangs denselben Anfrageinhalt und denselben Wert für Idempotency-Key bei.
Antwort
{
  "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-After angegebene Anzahl an Sekunden. Behalte beim Wiederholen eines Schreibvorgangs denselben Anfrageinhalt und denselben Wert für Idempotency-Key bei.
Antwort
{
  "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-After angegebene Anzahl an Sekunden. Behalte beim Wiederholen eines Schreibvorgangs denselben Anfrageinhalt und denselben Wert für Idempotency-Key bei.
Antwort
{
  "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-Key und ändere den Anfrageinhalt nicht.
Antwort
{
  "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.
Antwort
{
  "error": {
    "code": "gateway.bad_response",
    "fields": null,
    "message": "The API gateway could not obtain a valid response."
  },
  "meta": {
    "request_id": "example-request"
  }
}

503service.unavailableDie API kann die Anfrage vorübergehend nicht bearbeiten.
Vorgehensweise
Wenn die Antwort den Header Retry-After enthält, warte vor dem nächsten Versuch die dort angegebene Anzahl an Sekunden. Andernfalls versuche es in einem Moment erneut. Tritt der Fehler wiederholt auf, wende dich mit der Anfrage-ID an den technischen Support von Shopently.
Wiederholungsregeln
Wiederhole die Anfrage nach der oben beschriebenen Wartezeit. Verwende beim Wiederholen eines Schreibvorgangs denselben Wert für Idempotency-Key und ändere den Anfrageinhalt nicht.
Antwort
{
  "error": {
    "code": "service.unavailable",
    "fields": null,
    "message": "The API is temporarily unavailable."
  },
  "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-Key und ändere den Anfrageinhalt nicht.
Antwort
{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}