5. API Errors

HTTP codes

Code	Meaning
200	OK. Request completed, including idempotent “already exists” responses.
201	Created. Resource created.
401	Unauthorized. Authentication error: key, signature, or timestamp.
403	Forbidden. Access denied.
404	Not Found. Payout or PayIn by external_id was not found.
422	Unprocessable Entity. Validation or business rule error.
500	Internal Server Error. Server error.

Common messages

Message	Cause	Action
API key required	X-API-Key header not sent.	Add a valid API 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, invalid, or expired X-Timestamp.	Send current UTC time within the allowed window.
Invalid signature	Signature does not match.	Verify HMAC-SHA256 formula.
external_id is required	external_id not sent.	Send external_id for create requests.
amount must be a positive decimal string	Amount missing, not a string, invalid, or not positive.	Send amount as a string, for example "5000.00".
currency is required	Currency not specified.	Send ISO currency code.
card_number is required	Card number not specified for payout.	Send recipient wallet, account, or card number.
callback_url must be a valid URL	callback_url is not valid.	Use a valid URL or omit the field.
Shop currency mismatch. Expected X.	Request currency does not match shop currency.	Use the shop currency.
Insufficient balance...	Not enough balance for payout.	Top up balance or reduce amount.
Payout not found / PayIn not found	No operation found for the resolved shop scope.	Check identifier and shop_code.

Example response

Standard

{
  "message": "Invalid API key",
  "code": "unauthorized",
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

Validation

{
  "message": "amount must be a positive decimal string",
  "code": "validation_error",
  "errors": [
    {
      "field": "amount",
      "message": "amount must be a positive decimal string"
    }
  ],
  "error": {
    "code": "validation_error",
    "message": "amount must be a positive decimal string"
  }
}