Error handling

Envelope

All 4xx/5xx JSON errors:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "limit must be between 1 and 250",
    "request_id": "req_01JABCDEF...",
    "param": "limit",
    "docs_url": "https://developers.ioneshop.eu/errors/INVALID_PARAMETER"
  }
}

HTTP status map

Status	Category	Example codes
400	Validation	INVALID_PARAMETER, INVALID_JSON
401	Authentication	UNAUTHORIZED, KEY_REVOKED, TOKEN_EXPIRED
403	Authorization	FORBIDDEN, INSUFFICIENT_SCOPE, TENANT_SUSPENDED, TENANT_MISMATCH
404	Not found	NOT_FOUND
409	Conflict	CONFLICT, INVALID_STATE_TRANSITION, IDEMPOTENCY_KEY_REUSED
422	Semantic validation	UNPROCESSABLE_ENTITY
429	Rate limit	RATE_LIMITED
500	Server	INTERNAL_ERROR
502 / 503	Upstream / capacity	BAD_GATEWAY, SERVICE_UNAVAILABLE

Client handling

Code	Action
UNAUTHORIZED	Refresh token / check key; do not retry blindly
INSUFFICIENT_SCOPE	Request new key/scopes
RATE_LIMITED	Honor Retry-After
INVALID_PARAMETER	Fix request; do not retry same body
CONFLICT / IDEMPOTENCY_KEY_REUSED	Re-fetch resource; reuse prior result or new Idempotency-Key
INTERNAL_ERROR	Retry with backoff + jitter; include request_id in ticket

Logging

Log request_id, error.code, HTTP status — never Authorization headers or webhook secrets.