FehlerbehandlungError Handling

Die BEEP! API verwendet konventionelle HTTP-Statuscodes und gibt strukturierte JSON-Fehlerobjekte zurück.

The BEEP! API uses conventional HTTP status codes and returns structured JSON error objects.

Fehler-ObjektError Object

Bei einem Fehler enthält die Antwort immer:

On error the response always contains:

HTTP-StatuscodesHTTP Status Codes

Code	BedeutungMeaning	WannWhen
200	OK	Anfrage erfolgreichRequest successful
400	Bad Request	Fehlende/ungültige ParameterMissing/invalid parameters
401	Unauthorized	Kein oder ungültiger API-KeyNo or invalid API key
403	Forbidden	Key hat keine Berechtigung für diesen Endpoint (Paket-Beschränkung)Key has no permission for this endpoint (package restriction)
404	Not Found	Ressource (Store, Produkt …) nicht gefundenResource (store, product …) not found
405	Method Not Allowed	Nur POST wird unterstütztOnly POST is supported
429	Too Many Requests	Rate Limit überschrittenRate limit exceeded → Rate Limits
500	Internal Server Error	Serverfehler, bitte erneut versuchenServer error, please try again

FehlercodesError Codes

Das error-Feld enthält einen maschinenlesbaren Code:

The error field contains a machine-readable code:

Code	HTTP	BeschreibungDescription
MISSING_AUTH_HEADER	401	Authorization-Header fehltAuthorization header missing
INVALID_API_KEY	401	Key ungültig oder widerrufenKey invalid or revoked
SUBSCRIPTION_INACTIVE	403	Kein aktives Abo (Live-Modus erfordert aktive Subscription)No active subscription (live mode requires active subscription)
ENDPOINT_NOT_ALLOWED	403	Dein Paket hat keinen Zugriff auf diesen EndpointYour package has no access to this endpoint
RATE_LIMIT_EXCEEDED	429	Zu viele Anfragen, warte bisToo many requests, wait until Retry-After
INVALID_ACTION	400	Unbekannter Endpoint / ActionUnknown endpoint / action
MISSING_FIELDS	400	Pflichtfelder fehlen im Request-BodyRequired fields missing in request body
STORE_NOT_FOUND	404	Store-ID existiert nichtStore ID does not exist
PRODUCT_NOT_FOUND	404	Produkt nicht gefunden (Barcode oder ID)Product not found (barcode or ID)
INTERNAL_ERROR	500	Unerwarteter ServerfehlerUnexpected server error

Best Practices

• Prüfe immer success im Response-Body statt nur den HTTP-Code.Always check success in the response body, not just the HTTP code.
• Retry bei 429 & 500: Implementiere exponentielles Backoff. Bei 429 enthält der Header Retry-After die Wartezeit in Sekunden.Retry on 429 & 500: Implement exponential backoff. On 429 the Retry-After header contains the wait time in seconds.
• Logge den error-Code: Für Debugging immer den maschinenlesbaren Code speichern.Log the error code: Always save the machine-readable code for debugging.
• Zeige dem User die message: Das message-Feld ist für menschliche Leser gedacht.Show the user the message: The message field is intended for human readers.
• Unterscheide Client- vs. Server-Fehler: 4xx = dein Code hat ein Problem. 5xx = unser Problem, automatisch retrien.Distinguish client vs. server errors: 4xx = your code has a problem. 5xx = our problem, retry automatically.