Fehler und Codes
Jeder Fehler ist ein Problem-Objekt nach RFC 9457 mit einem stabilen code. Werten Sie code aus, nicht den Text.
Die API ist gebaut und getestet. Das Hosting unter api.garanify.com ist in Vorbereitung; bis dahin läuft sie lokal. Schlüssel gibt es auf Anfrage.
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
Request-Id: req_8Kd2mVq7Xc1LpT4z
{
"type": "https://garanify.com/en/developers/errors/#validation_failed",
"title": "Request does not match the schema",
"status": 422,
"code": "validation_failed",
"detail": "The request body does not match the schema.",
"errors": [
{ "path": "/garan/years", "message": "must be multiple of 0.5" }
],
"requestId": "req_8Kd2mVq7Xc1LpT4z"
} typeverweist auf den Eintrag unten,titleist englisch und kann sich ändern,detailerklärt den Einzelfall.errors[]gibt es beivalidation_failedund beim Massen-Upsert, mit JSON-Pointer inpath.requestIdentspricht dem HeaderRequest-Id. Nennen Sie ihn, wenn Sie den Support fragen. Die SDKs legen ihn inerror.requestIdab.- Neue Codes können dazukommen. Behandeln Sie unbekannte Codes nach dem HTTP-Status.
Alle Codes
| Code | Status | Bedeutung | Was tun |
|---|---|---|---|
missing_key | 401 | API-Schlüssel fehlt | Senden Sie Authorization: Bearer gfy_sk_…. |
invalid_key | 401 | Schlüssel ungültig, abgelaufen oder gesperrt | Schlüssel im Konto prüfen; nach einer Rotation den neuen verwenden. |
key_in_query | 400 | Secret Key in der URL | Secret Keys nur im Header senden. Sperren Sie den Schlüssel: er kann jetzt in Logs stehen. |
secret_key_required | 403 | Endpunkt braucht einen Secret Key | Publishable Keys lesen nur öffentliche Daten. Rufen Sie den Endpunkt vom Server auf. |
origin_not_allowed | 403 | Herkunft nicht erlaubt | Die Seite liegt nicht auf einer Domain des Shops. Domain mit PATCH /v1/shops/{shop} ergänzen. |
shop_not_found | 404 | Shop nicht gefunden | Die Shop-ID im Pfad passt nicht zum Schlüssel. |
product_not_found | 404 | Produkt nicht gefunden | Produkt mit PUT …/products/{sku} registrieren; SKU URL-kodieren. |
key_not_found | 404 | Schlüssel nicht gefunden | Key-ID (key_…) aus GET …/keys verwenden, nicht das Geheimnis. |
not_found | 404 | Nicht gefunden | Pfad und Version (/v1) prüfen. |
method_not_allowed | 405 | Methode nicht erlaubt | Erlaubte Methoden stehen im Header Allow. |
invalid_json | 400 | Body ist kein gültiges JSON | Content-Type: application/json und gültiges JSON senden. |
validation_failed | 422 | Anfrage passt nicht zum Schema | errors[] nennt jedes Feld mit Pfad. |
payload_too_large | 413 | Body zu groß | Höchstens 256 KB, beim Massen-Upsert 4 MB. |
plan_required | 403 | Funktion braucht Pro oder Agentur | Lizenz mit PUT …/license verknüpfen. |
garan_limit_reached | 403 | Free-Grenze für GARAN-Produkte erreicht | Vorhandene Etiketten bleiben sichtbar. Für mehr Produkte Pro verknüpfen. |
idempotency_key_reused | 422 | Idempotency-Key mit anderem Body | Für jede neue Anfrage einen neuen Schlüssel verwenden. |
last_secret_key | 409 | Letzter Secret Key | Erst einen neuen Secret Key anlegen, dann den alten sperren. |
license_invalid | 422 | Lizenzschlüssel unbekannt oder gesperrt | Schlüssel erneut aus dem Garanify-Konto kopieren. |
license_shop_limit | 409 | Alle Shop-Plätze der Lizenz belegt | Platz im Konto freigeben oder einen anderen Shop lösen. |
account_shop_limit | 409 | Höchstzahl an Shops im Konto erreicht | Bis zu 100 Shops je Konto; für mehr den Support anschreiben. |
license_domain_locked | 409 | Hauptdomain an die Lizenz gebunden | Lizenz lösen, Domain ändern, Lizenz neu verknüpfen. |
billing_unavailable | 503 | Lizenzdienst nicht erreichbar | In einer Minute erneut versuchen. Bestehende Lizenzen gelten weiter. |
webhook_url_invalid | 422 | Webhook-URL nicht erlaubt | HTTPS auf einem öffentlichen Hostnamen verwenden. |
live_key_required | 403 | Endpunkt braucht einen Live-Schlüssel | Test-Shops haben alle Funktionen ohne Lizenz. Lizenzen nur mit Live-Shops verknüpfen. |
rate_limited | 429 | Zu viele Anfragen | Nach Retry-After Sekunden erneut senden. |
internal_error | 500 | Interner Fehler | Erneut versuchen; bleibt der Fehler, Support mit Uhrzeit kontaktieren. |
Warum kein Etikett?
Ein Produkt ohne Etikett ist kein Fehler der Anfrage. Die Auflösung nennt den Grund in errors[].code:
| Code | Bedeutung |
|---|---|
years_missing | Die Herstellergarantie in Jahren fehlt. |
years_too_low | GARAN nur bei einer Herstellergarantie von mehr als 2 Jahren. |
years_not_half | Nur ganze oder halbe Jahre sind erlaubt. |
years_implausible | Die Garantiedauer ist unplausibel (mehr als 99 Jahre). |
brand_missing | Die Marke fehlt: brand oder garan.brand senden. |
model_missing | Die Modellkennung fehlt: mpn oder garan.model senden. |