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.
429	Too Many Requests. Rate limit exceeded; retry after the response Retry-After value.
503	Service Unavailable. Canonical-signature replay protection storage is unavailable.
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.
Request ID required / Invalid request ID / Replay detected	The transaction-history request ID is missing, invalid, or already used.	Send a fresh 1–128 character request ID matching [A-Za-z0-9._:-]+.
IP not allowed	Merchant IP whitelist rejected the request source.	Add the source to the merchant whitelist or use an allowed source.
Rate limit exceeded	The merchant API key and selected shop exceeded the request limit.	Wait for the Retry-After interval before retrying.
Replay protection unavailable	Transaction-history replay storage is unavailable, so signed requests fail closed.	Retry later; do not fall back to an unsigned request.
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	ARS 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	The selected endpoint requires an active shop and the code is unknown or inactive. Transaction History is an exception and permits inactive shops.	Check shop_code and endpoint requirements.
Default shop is not configured for this merchant	No default shop is configured. Endpoints that create operations additionally require it to be active.	Configure a default 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"
}

Authentication, IP whitelist, and replay-protection middleware errors can use this message-only form. Application validation and business errors use the structured envelope below.

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. Depending on the endpoint, this value can be a list or an object keyed by field. For compatibility, the same details can also be available as details.errors and error.details.errors.

Transaction or business limit violations return HTTP 422 with a stable code value and text in message. Request-rate limiting is separate and returns HTTP 429.