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 account number.
callback_url must be a valid URL	callback_url is not valid.	Use a valid URL or omit the field.
Invalid paymentData	BOB payout paymentData validation failed.	Check recipient_name, bank_name, and field-level validation details.
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	Request was sent 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 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.
Only one payout per request is allowed...	Array of payouts was sent in the request body.	Send one payout per request.
Only one payin per request is allowed...	Array of payins was sent in the request body.	Send one payin per request.

Example response

Standard

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

Validation

{
  "message": "Invalid paymentData",
  "code": "validation_error",
  "errors": [
    {
      "field": "recipient_name",
      "message": "Field is required"
    }
  ],
  "error": {
    "code": "validation_error",
    "message": "Invalid paymentData"
  }
}

Field-level validation details are returned in errors. For compatibility, the same list can also be available as details.errors and error.details.errors.

Limit exceeded and other business errors return HTTP code 422 with a stable code value and text in message.