Fehler und Wiederherstellung

Entscheiden Sie anhand stabiler Fehlercodes, ob Sie korrigieren, warten oder wiederholen müssen.

Vorgehensweise

Verzweigen Sie anhand von HTTP-Status und error.code, nicht anhand des menschenlesbaren error.message.
401 verlangt gültige Authentifizierung, 403 passende Zugriffsrechte oder Tarifänderungen und 409 eine Prüfung des Vorgangs oder der Ressourcenversion.

Zugriff verweigert und Wiederholungen

401: 401 bedeutet nicht immer, dass das Token abgelaufen ist. Ist es abgelaufen, fordern Sie ein neues an und wiederholen Sie den Lesezugriff höchstens einmal. Liefert die Token-Anforderung 401, prüfen Sie den Schlüssel und stoppen Sie automatische Versuche.
403: Prüfen Sie bei 403 Berechtigungen, IP-Beschränkungen und Tarif. Ein neues Token stellt entzogenen Zugriff nicht wieder her.

Authentifizierung

Wiederholungsregeln

Vorübergehende Fehler nur begrenzt mit zunehmender und zufällig variierter Wartezeit wiederholen.
Retry-After beachten, sofern vorhanden.
Nach einem Schreib-Timeout kann das Ergebnis unbekannt sein: Bei Wiederholung desselben logischen Vorgangs Idempotency-Key und Anfrage unverändert beibehalten.
Der folgende Katalog beschreibt alle veröffentlichten Fehlercodes.

Sicheres Schreiben

Anfragelimits

422 / 409

Bei Preisen führen ein ungültiges Währungsformat oder eine unzulässige Anzahl von Nachkommastellen zu 422 request.validation_failed.
Ein gültiger Währungscode, der nicht zur gewählten Preisliste passt, führt zu 409 resource.version_conflict.
Prüfe vor einem erneuten Versuch den Kontext und die Versionen.

Fehlerkatalog

400request.malformedDie Anfrage kann nicht eingelesen werden.

Vorgehensweise: JSON-Syntax, URL-Kodierung und Anfragestruktur prüfen.
Wiederholungsregeln: Erst nach Korrektur der Anfrage erneut versuchen.

JSON

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

JSON

{
  "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: Für die Token-Anforderung ApiKey verwenden, für Ressourcenoperationen Bearer.
Wiederholungsregeln: Erst nach Korrektur der Authentifizierung erneut versuchen; wiederholte ungültige Token-Anfragen vermeiden.

JSON

{
  "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: Den Shop-Betreiber den Eingangsweg prüfen lassen. Keine Weiterleitungsheader selbst einfügen.
Wiederholungsregeln: Erst erneut versuchen, wenn die erforderlichen Zugriffsrechte wirksam sind.

JSON

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

JSON

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

JSON

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

JSON

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

JSON

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

JSON

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

JSON

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

JSON

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

JSON

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

JSON

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

JSON

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

JSON

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

JSON

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

JSON

{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "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.

JSON

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

JSON

{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "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.

JSON

{
  "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: Mindestens die in Retry-After angegebene Sekundenzahl warten und eine zufällige Verzögerung hinzufügen. Bei demselben Schreibvorgang Schlüssel und Inhalt beibehalten.

JSON

{
  "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: Mindestens die in Retry-After angegebene Sekundenzahl warten und eine zufällige Verzögerung hinzufügen. Bei demselben Schreibvorgang Schlüssel und Inhalt beibehalten.

JSON

{
  "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: Mindestens die in Retry-After angegebene Sekundenzahl warten und eine zufällige Verzögerung hinzufügen. Bei demselben Schreibvorgang Schlüssel und Inhalt beibehalten.

JSON

{
  "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: Die Anfragekennung notieren und bei anhaltendem Fehler den Betreiber kontaktieren. Keine Zugangsdaten protokollieren.
Wiederholungsregeln: Begrenzt mit zunehmender, zufällig variierter Wartezeit wiederholen. Bei demselben Schreibvorgang den ursprünglichen Idempotency-Key und unveränderten Inhalt beibehalten.

JSON

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

JSON

{
  "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: Retry-After beachten, sofern vorhanden. Bei anhaltender Störung die Anfragekennung aufbewahren.
Wiederholungsregeln: Begrenzt mit zunehmender, zufällig variierter Wartezeit wiederholen. Bei demselben Schreibvorgang den ursprünglichen Idempotency-Key und unveränderten Inhalt beibehalten.

JSON

{
  "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: Die Anfragekennung aufbewahren und das Ergebnis des Schreibvorgangs als unbekannt behandeln.
Wiederholungsregeln: Begrenzt mit zunehmender, zufällig variierter Wartezeit wiederholen. Bei demselben Schreibvorgang den ursprünglichen Idempotency-Key und unveränderten Inhalt beibehalten.

JSON

{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}