Error Handling

When something cannot be done, the platform refuses cleanly: nothing partial ever happens, and the refusal says why. Here is how to read the outcomes — in operational terms.

The Outcomes Your Team Will Meet

What the response means	What to do
The request itself has a problem — wrong code, not enough points, a limit was hit, a centre code that is not on your list	Read the stated reason; it names the issue directly (e.g. a fraud limit, an expired code)
The feature is switched off for your tenant	Talk to your account team, or check the Settings page — it is a configuration choice, not an error
The thing referenced does not exist	An unknown customer, a rule that belongs to another tenant, or a redemption that is no longer pending
Already done	The operation succeeded earlier — a repeat was recognized and ignored. Treat it as success
Too late	The confirmation window passed, or the notification for that transaction was already sent. Start the calculation again — nothing happened
A platform fault	Rare; retrying is always safe because nothing partial was recorded

Two Habits Worth Building

“Already done” is good news. It means your safety reference did its job — the original attempt landed and the repeat changed nothing.
“Too late” has one fix. Recalculate and confirm within the new window. There is never anything to undo.

For Developers: the Status Codes

Code	Meaning on this platform	Typical cause
`400`	The request was refused before anything changed	Validation failure, invalid or expired OTP, insufficient points for a reversal or penalty, a `store_code` outside the centre list, no active configuration when saving settings
`403`	The feature is disabled or not allowed for this tenant	Earning or redemption switched off, OTP enabled without a template, debits not permitted by policy
`404`	The referenced record does not exist in this tenant	Unknown phone, unknown rule, no pending redemption for that `redemption_id`
`409`	Already done — the idempotency key was seen before	A repeated `confirm-transaction`, `reversal_code` or `operation_code`; a review that was already resolved
`410`	The window has passed	`confirm-transaction` after the confirmation window; `send-notification` for a transaction already sent or expired
`500`	A platform fault	Retry safely — nothing partial was recorded

Keys that make repeats harmless

`reference_id` on confirmations, `redemption_id` on redemptions, `reversal_code` on reversals and `operation_code` on bonus, penalty and adjustment calls. Send them once per business event and a retry can never double-count.

For developers

Exact status codes, error bodies and retry semantics for every operation: follow any operation link, or open the full reference from Endpoints Overview.

The Outcomes Your Team Will Meet

Two Habits Worth Building

For Developers: the Status Codes

On this page