Error Handling

Every failure is JSON with a message. Some carry more, and the difference between them is what decides whether your plugin retries, hides the layaway option, or stops and tells the merchant to go and fix something.

The statuses

Status	Meaning	What to do
400	An Idempotency-Key longer than 255 characters was sent.	Shorten the key.
401	The key is missing, unknown, or revoked — or paired with a client id from the other mode, which the response names.	Stop. The merchant must reconnect, or pair the key with the client id shown in the same mode of the dashboard.
403	With a reason: layaway is unavailable for this merchant or this customer's state. Without one: the merchant is not cleared to transact.	With a reason, hide the layaway option and show message. Without one, stop — this is a configuration problem.
404	No session with that token — unknown, never created, or belonging to another merchant or mode.	Stop. Do not retry; a token does not become valid later.
409	This Idempotency-Key was already used with a different request body.	Fixable. Send the original body, or use a new key.
422	The request is wrong — usually an order total outside the merchant's range. Also a session asked to confirm or cancel after it already resolved.	Fixable. Read errors for the field.
429	Rate limited.	Back off for Retry-After seconds.
5xx	Something failed on ShotPay's side.	Retry with backoff.

Refusal reasons

A 403 that carries a reason is layaway being unavailable rather than the caller being wrong. The message beside it is written to be safe to show a customer.

{
  "message": "Layaway is not offered in this state.",
  "reason": "state_unavailable"
}

reason	Meaning
platform_disabled	Layaway is off across the platform. Temporary.
merchant_overridden	Layaway is switched off for this account by ShotPay.
state_unavailable	Layaway is not offered in the customer's state.
state_excluded	The program excludes the customer's state outright.
merchant_disabled	The merchant has not turned layaway on in their settings.
merchant_inactive	The account is not cleared to transact in this mode.

Only state_unavailable and state_excluded vary per customer; the rest are account-level.