FehlerbehandlungError Handling

Strukturierte JSON-Fehlerobjekte mit maschinenlesbaren Codes.

Structured JSON error objects with machine-readable codes.

Fehler-ObjektError Object

Error Response: 4xx / 5xx

{ "success": false, "error": "INVALID_API_KEY", "message": "The provided API key is invalid or has been revoked.", "statusCode": 401 }

Globale Response-HeaderGlobal Response Headers

Header	BeschreibungDescription	BeispielExample
`X-API-Version`	Aktuelle API-VersionCurrent API version	`1.3.0`
`X-Request-Id`	Eindeutige Request-ID für DebuggingUnique request ID for debugging	`req_1740650400000_a3bF`
`X-RateLimit-Limit`	Max. Requests/MinuteMax. requests/minute	`600`
`X-RateLimit-Remaining`	Verbleibende RequestsRemaining requests	`587`

Diese Header erscheinen auf jeder Response, auch bei 401, 403 und 500.These headers appear on every response, including 401, 403 and 500.

HTTP-StatuscodesHTTP Status Codes

Code	BedeutungMeaning	WannWhen
`200`	OK	Anfrage erfolgreichRequest successful
`400`	Bad Request	Fehlende oder ungültige ParameterMissing or invalid parameters
`401`	Unauthorized	Kein oder ungültiger API-KeyNo or invalid API key
`403`	Forbidden	Key hat keine Berechtigung (Paket-Beschränkung). Response enthält `upgradeUrl`.Key has no permission (package restriction). Response contains `upgradeUrl`.
`404`	Not Found	Ressource nicht gefundenResource not found
`405`	Method Not Allowed	HTTP-Methode nicht erlaubt (z.B. PUT, DELETE, PATCH)HTTP method not allowed (e.g. PUT, DELETE, PATCH)
`429`	Too Many Requests	Rate Limit überschrittenRate limit exceeded → Rate Limits
`500`	Internal Server Error	Serverfehler, bitte erneut versuchenServer error, please retry

FehlercodesError Codes

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)No active subscription (live mode)
`ENDPOINT_NOT_ALLOWED`	403	Endpoint nicht im Paket enthaltenEndpoint not in package
`RATE_LIMIT_EXCEEDED`	429	Zu viele Anfragen. `Retry-After` Header beachten.Too many requests. Check `Retry-After` header.
`INVALID_ACTION`	400	Unbekannter Endpoint / ActionUnknown endpoint / action
`MISSING_FIELDS`	400	Pflichtfelder fehlen im BodyRequired fields missing in body
`STORE_NOT_FOUND`	404	Store-ID existiert nichtStore ID does not exist
`PRODUCT_NOT_FOUND`	404	Produkt nicht gefundenProduct not found
`INTERNAL_ERROR`	500	Unerwarteter ServerfehlerUnexpected server error

Best Practices

Prüfe successCheck success

Immer den Body prüfen, nicht nur den HTTP-Code.Always check the body, not just the HTTP code.

Retry bei 429 + 500Retry on 429 + 500

Exponentielles Backoff. Bei 429: Retry-After beachten.Exponential backoff. On 429: check Retry-After.

Logge den error-CodeLog the error code

Maschinenlesbarer Code für Debugging.Machine-readable code for debugging.

4xx vs. 5xx

4xx = dein Code. 5xx = automatisch retrien.4xx = your code. 5xx = retry automatically.

In der Sandbox geben Endpoints mit implementierten Sandbox-Handlern 200 zurück (auch bei ungültigen Parametern). Das Feld _sandbox: true markiert Sandbox-Antworten.

In the Sandbox, endpoints with implemented sandbox handlers return 200 (even with invalid parameters). The field _sandbox: true marks sandbox responses.