6. API errors

All errors are returned in JSON format with a message field (and errors for validation details when applicable).

Error response format

{
  "message": "Error description text"
}

For validation errors (e.g. on paymentData fields):

{
  "message": "Invalid paymentData",
  "errors": [
    { "field": "holder", "message": "Field is required" }
  ]
}

HTTP codes

Code	Meaning
200	OK — request completed (including idempotent “already exists” response).
201	Created — resource created.
401	Unauthorized — authentication error (key, signature, timestamp).
403	Forbidden — access denied.
404	Not Found — object not found (payout/payin by external_id).
422	Unprocessable Entity — validation or business rule error.
500	Internal Server Error — server error.

Common messages (message)

Message	Cause	Action
API key required	X-API-Key header not sent.	Add header with a valid key.
Invalid API key	Key not found or inactive.	Check key and status in the dashboard.
Timestamp required / Invalid timestamp format / Timestamp window exceeded	Missing or invalid X-Timestamp, or request “expired”.	Send current time (UTC) within the ±60 sec window.
Invalid signature	Signature does not match.	Verify formula: HMAC-SHA256(secret, timestamp + body).
external_id is required	external_id not sent in request body.	Required for creating payout/payin.
amount must be a positive number	amount missing, not a number, or ≤ 0.	Send a positive number.
currency is required	Currency not specified (for payout or payin).	Send ISO currency code (3 chars).
card_number is required	Card number not specified (for payout).	Send recipient card number.
callback_url must be a valid URL	callback_url is not a valid URL.	Use a valid URL or omit the field.
Invalid paymentData	Validation failed against shop schema.	Check errors field and shop field schema.
Shop with code 'X' not found or inactive for this merchant	Unknown or inactive explicit shop_code.	Use an active shop code that belongs to the merchant.
Default shop is not configured for this merchant	Read request without shop_code, but no default active shop exists.	Configure a default active shop or pass shop_code.
Shop currency mismatch. Expected X.	Request currency does not match shop currency.	Use the shop’s currency.
Insufficient balance...	Not enough balance for payout.	Top up balance or reduce amount.
Payout not found / PayIn not found	No operation with this external_id (and shop_code).	Check identifier and shop_code if needed.
Only one payout per request is allowed...	Array of payouts sent in body.	Send one payout per request.
Only one payin per request is allowed...	Array of payins sent in body.	Send one payin per request.
Invalid transaction_type	Invalid transaction_type in GET /api/v1/transactions.	Use payout, payin, or all.
Invalid status	Invalid status in GET /api/v1/transactions.	Use only external statuses: pending, success, failed, canceled, refunded, expired.

Limit exceeded and other business errors return code 422 with text in message; contact support for format details if needed.