Errors

Response envelope

Successful responses:

{
  "success": true,
  "message": "Points issued successfully",
  "data": { ... }
}

Errors:

{
  "success": false,
  "error": {
    "message": "Customer not found. Check the user_id or identifier."
  }
}

Status codes

Code	Meaning
`200` / `201`	Success
`400`	Validation error or business rule violated (insufficient balance, expired code, cooldown active…) — the `error.message` explains which
`401`	Missing, malformed, or revoked API key
`403`	Business account not approved (pending, blocked, or suspended)
`404`	Resource not found — also returned for resources that belong to another business
`409`	A request with the same `Idempotency-Key` is still in progress, or a limit/state conflict — see limit and delivery errors
`429`	Rate limit exceeded — see Rate limits
`500`	Unexpected server error — safe to retry with an `Idempotency-Key`
`502`	An endpoint you supplied failed. Today that is only external digital reward provisioning (`DIGITAL_PROVISION_FAILED`) — the redemption was cancelled and nothing was charged. See digital provisioning errors

Common error messages

Message	What to do
`Customer not found. Check the user_id or identifier.`	The email/phone/external ID doesn’t match a Rigaly user. Customers must have a Rigaly account before earning points.
`Provide exactly one of "user_id" or "identifier"`	Send one customer reference, not both.
`Insufficient points. ...`	The customer’s balance can’t cover the deduction/redemption.
`Redemption code has already been completed`	The code was consumed before — check `GET /redemptions/{code}` for its status.
`Redemption code has expired`	Redemption codes are time-limited; the customer should redeem the reward again in the app.
`This code has already been used`	Mass codes are single-use; this one was claimed.
`Maximum of 10 active API keys reached. ...`	Revoke an unused key in the dashboard before creating another.
`Failed to refund redemption points: ...`	Cancelling a fulfillment could not pay the customer’s points back. The refund runs first, so nothing was applied — no points moved and the fulfillment status is unchanged. Retry the same request.

Limit and delivery errors

Reward redemption caps, raffle entry caps, and the shipping/digital delivery modes return machine-readable codes instead of prose. Some carry a :<value> suffix so you can render the number without a second call.

Message	HTTP	Where	What it means
`REWARD_LIMIT_REACHED:<max>`	409	`POST /rewards`, `PATCH /rewards/{id}`	You sent `active: true` for a reward that is already at its redemption cap. Raise `max_redemptions` in the same request.
`REWARD_LIMIT_BELOW_CURRENT:<count>`	400	`PATCH /rewards/{id}`	`max_redemptions` was set below the redemptions already completed. `<count>` is the current total — you can only go up.
`REDEMPTION_NOT_IN_STORE:<mode>`	400	`GET /redemptions/{code}`, `POST /redemptions/{code}/complete`	The code belongs to a `shipping` or `digital` reward. Those complete themselves at redemption — there is nothing to validate.
`REDEMPTION_LIMIT_REACHED:<max>`	409	`GET /redemptions/{code}`, `POST /redemptions/{code}/complete`	The reward hit its redemption cap after this code was issued, so the code can’t be honored.
`REDEMPTION_NOT_SHIPPABLE`	400	`PATCH /redemptions/{id}/fulfillment`	That redemption has no fulfillment lifecycle — it isn’t a shipping one.
`FULFILLMENT_ALREADY_CANCELLED`	409	`PATCH /redemptions/{id}/fulfillment`	The redemption was already cancelled; cancelled is terminal. The first cancel’s points refund is not paid out again — retrying can’t double-credit the customer.
`MAX_ENTRIES_BELOW_CURRENT`	400	`PATCH /raffles/{id}`	`max_entries` was set below the entries already recorded. The ceiling only moves up.
`FIELDS_LOCKED`	400	`PATCH /raffles/{id}`	The raffle has entries, so `points_cost`, `entries_per_user`, `winners_count` and `max_entries_mode` are frozen. `max_entries` is still editable.

Two more surface to your customers in the Rigaly app rather than to your integration — worth knowing when you read a support ticket:

Message	HTTP	What it means
`RAFFLE_FULL:<remaining>`	409	The raffle reached its `max_entries` ceiling. `<remaining>` is how many entries would still have fit, so the app can say “only 2 spots left”. Raising the cap reopens entries immediately.
`SHIPPING_DETAILS_REQUIRED` / `DIGITAL_ASSET_MISSING`	400 / 409	A shipping reward was redeemed without an address, or a `static` digital reward has no `digital_asset_value` configured. The second one means the reward is misconfigured — fix `digital_asset_value`.

Digital provisioning errors

A digital reward draws its value from a digital_asset_source: a fixed value (static), a batch of one-time codes you upload (pool), or an HTTPS endpoint of yours that Rigaly calls at redemption time (external). These codes cover the pool and webhook endpoints, plus the two failures a redemption itself can hit. Full behavior: digital provisioning sources.

Message	HTTP	Where	What it means
`DIGITAL_POOL_EXHAUSTED`	409	Redemption, `PATCH /rewards/{id}`	The reward’s code pool is empty. At a redemption the reward has just switched itself off (`deactivated_by_pool: true`); on a patch, you switched a reward to `digital_asset_source: "pool"` with `active: true` before any values existed. Upload values with `POST /rewards/{id}/pool/codes` and the reward reopens by itself. (Creating a pool reward never fails this way — it is parked inactive instead.)
`DIGITAL_PROVISION_FAILED`	502	Redemption	Your external endpoint didn’t produce a usable value — timeout, non-2xx, malformed body, a `type` that doesn’t match the reward, an `expires_at` in the past, a blocked address, or the reward’s circuit breaker being open. The redemption was cancelled: no points were taken and no fee was charged. Diagnose with `POST /rewards/{id}/webhook/test`.
`DIGITAL_WEBHOOK_NOT_CONFIGURED`	409	Redemption, `POST /rewards/{id}/webhook/test`	The reward is `external` but has no `digital_webhook_url`, or no signing secret. Set the URL on the reward, or issue a secret with `POST /rewards/{id}/webhook/rotate-secret`.
`REWARD_NOT_POOL_SOURCED`	400	`GET`/`POST`/`DELETE /rewards/{id}/pool…`	The reward’s `digital_asset_source` isn’t `pool`, so it has no code pool.
`REWARD_NOT_EXTERNALLY_SOURCED`	400	`POST /rewards/{id}/webhook/test`, `POST /rewards/{id}/webhook/rotate-secret`	The reward’s `digital_asset_source` isn’t `external`, so there is no endpoint to test and no secret to rotate.
`POOL_UPLOAD_EMPTY`	400	`POST /rewards/{id}/pool/codes`	Nothing in the request was storable — every value was blank, over 500 characters, or already in the pool.
`POOL_UPLOAD_TOO_LARGE:<max>`	400	`POST /rewards/{id}/pool/codes`	More than `<max>` (5,000) values in one request. Split the list and upload in chunks.
`POOL_CAPACITY_EXCEEDED:<max>`	409	`POST /rewards/{id}/pool/codes`	The upload would push the pool past `<max>` (100,000) stored values. Nothing was stored — delete unconsumed values or shorten the upload.

POST /rewards/{id}/webhook/test is the exception to everything above: it returns HTTP 200 even when the test failed. Read data.ok, not the status code — a transport failure at your endpoint is a test result, not an API error.

See the reward delivery guide and the raffles guide for the behavior behind these.

Getting Started

Guides

Response envelope

Status codes

Common error messages

Limit and delivery errors

Digital provisioning errors

​Response envelope

​Status codes

​Common error messages

​Limit and delivery errors

​Digital provisioning errors

Response envelope

Status codes

Common error messages

Limit and delivery errors

Digital provisioning errors