Errors

Every failure has the same JSON shape, and status equals the HTTP status:

{
  "timestamp": "2026-10-06T14:03:11.482913Z",
  "status": 400,
  "error": "Bad Request",
  "details": "ccn must be between 13 and 19 characters. "
}

For validation errors details lists every violated rule, each ending in . .

Status	Meaning	Example details
400	Invalid field or broken rule	currency key cannot be null
400	Duplicate reference	Transaction reference code already exist!
400	Unknown or inactive MID	MID with name NOPE_MID does not exists in database
400	No x-api-key header	Field required.
400	Unsafe postback URL	postbackUrl is not allowed: ...
401	Wrong API key, or a key that is not this merchant’s
409	Idempotency key reused with a different body (/api/payment-session)	Idempotency-Key was already used with a different request.
429	Too many failed key attempts or requests from one address	Too many failed attempts. Try again later.
403	MID is shut down	MID with name ... is currently shut down...
404	Payment not found (lookup, refund)	Transaction with reference code ... not found!

What to do

• Never retry a 4xx unchanged. Fix the request.
• Network error or timeout on create: the payment may exist. Look it up by referenceCode before retrying.
• 429: wait and retry with a pause that grows each time. A wrong key keeps counting against you, so check it first.
• A DECLINED payment is a normal result, not an error. It returns 200 with status: "DECLINED".
• Show shoppers a generic message; keep message and details for your logs.

The Postman collection has a folder that triggers each of these on purpose.