Fehler
Jede Fehlerantwort ist ein JSON-Objekt mit mindestens einem error-Feld, das beschreibt, was schiefgelaufen ist. Statuscodes folgen strikt den HTTP-Konventionen.
Form
{
"error": "Menschenlesbare Beschreibung."
}Einige Fehler enthalten zusätzliche Felder. Kontingentfehler enthalten limit und tier:
{
"error": "Monthly quota exceeded.",
"limit": 1000,
"tier": "FREE"
}Statuscodes
| Feld | Typ | Beschreibung |
|---|---|---|
| 200 | OK | Erfolgreiche Antwort. |
| 400 | Bad Request | Fehlerhafte Parameter — typischerweise ein ungültiges Ablaufdatum beim Erstellen eines Schlüssels oder ein fehlerhafter Signup-Payload. |
| 401 | Unauthorized | Fehlender Schlüssel, ungültiger Schlüssel, abgelaufener Schlüssel oder nicht bestätigte E-Mail. Der Error-String unterscheidet die Fälle. |
| 403 | Forbidden | Gesperrtes Konto oder noch nicht bestätigte E-Mail. |
| 404 | Not Found | Kein Produkt mit dieser EAN. Wird nur vom Lookup-Endpoint zurückgegeben. |
| 429 | Too Many Requests | Monatskontingent, Per-Minute-Rate-Limit oder Authentifizierungsversuch-Throttle überschritten. Enthält Retry-After bei Per-Minute-Treffern. |
| 500 | Server Error | Unerwarteter Fehler auf unserer Seite. Sicher mit exponentiellem Back-off erneut versuchen. |
Häufige Error-Strings
| Feld | Typ | Beschreibung |
|---|---|---|
| "Missing API key…" | 401 | Kein Authorization-Header und kein X-API-Key-Header. |
| "Invalid API key." | 401 | Header vorhanden, aber der Schlüssel wurde nie ausgestellt, widerrufen oder passt nicht. |
| "API key expired." | 401 | Du hast ein Ablaufdatum für diesen Schlüssel gesetzt und dieses Datum ist vorbei. Erstelle einen neuen Schlüssel. |
| "Email not verified." | 403 | Das Konto existiert, aber der E-Mail-Bestätigungslink wurde nie angeklickt. |
| "Account suspended." | 403 | Das Konto wurde manuell gesperrt. Kontaktiere den Support. |
| "Product not found" | 404 | Keine EAN-Übereinstimmung. Hinweis: Wir validieren keine Prüfziffern — übergib genau das, was auf der Verpackung steht. |
| "Monthly quota exceeded." | 429 | Du hast dein vollständiges Tarifkontingent für den Kalendermonat verbraucht. Upgrade oder warte auf den Reset. |
| "Per-minute rate limit exceeded." | 429 | Burst-Rate zu hoch. Beachte Retry-After und verlangsame die Requests. |
| "Too many unauthenticated API requests…" | 429 | Zu viele Requests ohne Schlüssel von derselben Client-Adresse. Sende einen gültigen Schlüssel oder versuche es später erneut. |
| "Too many invalid API key attempts…" | 429 | Zu viele ungültige Schlüsselversuche von derselben Client-Adresse. Prüfe deine Konfiguration und versuche es später erneut. |
Retry-Empfehlung
- 4xx-Fehler: nicht erneut versuchen, ohne den Request zu ändern. Sie werden weiter fehlschlagen.
- 429 pro Minute: auf
Retry-Afterwarten, dann erneut versuchen. - 429 monatlich: nicht erneut versuchen. Upgrade oder auf den Kalender-Reset warten.
- 5xx: mit exponentiellem Back-off erneut versuchen (z. B. 1s, 2s, 4s, bis ~30s). Nach einigen Versuchen stoppen und den Fehler anzeigen.