Error handling

Consistent error response shape and status codes.

All errors share a uniform shape, consistent across the entire API.

Response shape

{
  "success": false,
  "statusCode": 400,
  "error": "Error message",
  "timestamp": "2026-06-17T10:30:00.000Z",
  "path": "/api/v2/orders"
}

A details field appears additionally for validation errors (the list of invalid fields).

Status codes

Code	Meaning	Typical cause
400	Bad Request	Invalid input, invalid identifier, validation error
401	Unauthorized	Missing or invalid API key
403	Forbidden	Missing role, no shop access, missing API-key permission
404	Not Found	Resource does not exist (shop, product, order…)
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error

Success responses

Successful responses have the shape { success: true, data, message? }. Some endpoints add contextual fields — for example, order creation returns redirectUrl, and a free order returns free: true.

Always check the success field rather than the HTTP code alone — the shape is consistent across the entire API.

Validation

The API rejects requests with invalid data before they are processed. Fields outside the schema are stripped, and types are converted automatically (e.g. numbers from the query string).