API reference Errors

Errors

Handle machine-readable error codes without duplicating rewards.

Error responses use a consistent envelope. Branch on error.code, not on exact wording in the human-readable message.

json

{
  "error": {
    "code": "DUPLICATE_EVENT",
    "message": "An allocation already exists for this campaign event.",
    "requestId": "req_example_0182",
    "existingRewardId": "rwd_demo0001"
  }
}

code, message, and requestId are required. existingRewardId is optional and is included only when an existing reward may safely be revealed within the caller's access scope. Example messages and request IDs are illustrative, not exact-match contracts.

Error codes#

Code	HTTP	Meaning	Handling
`INVALID_REQUEST`	`400`	The body, parameter, address, amount, or required header is malformed.	Correct the input; do not automatically retry unchanged.
`UNAUTHENTICATED`	`401`	The key is missing, invalid, or revoked.	Check the environment and server credential.
`FORBIDDEN`	`403`	The authenticated caller lacks the required permission.	Use an appropriately scoped key; do not broaden access unnecessarily.
`NOT_FOUND`	`404`	The resource is unknown or outside the accessible project.	Check the ID and authorized project without probing other tenants.
`IDEMPOTENCY_CONFLICT`	`409`	A write key was reused with different semantic content.	Recover the original persisted request; investigate the changed fields.
`DUPLICATE_EVENT`	`409`	The campaign/event-type/event-ID tuple already has a reward.	Read existingRewardId when supplied and compare the immutable allocation.
`INVALID_STATE`	`409`	The requested transition is not permitted.	Inspect current state; a frozen grant cannot be cancelled.
`BUDGET_EXCEEDED`	`422`	The allocation exceeds remaining authorized issuance capacity.	Coordinate authorization or reduce future program spending; do not silently alter an earned reward.
`GRANT_LIMIT_EXCEEDED`	`422`	The amount exceeds the approved per-grant maximum.	Review program configuration; do not split a reward merely to bypass controls.
`RECIPIENT_NOT_ALLOWED`	`422`	The destination is outside the approved recipient policy.	Resolve recipient eligibility or canary access before issuing.
`CAMPAIGN_PAUSED`	`409`	New issuance is paused.	Wait for an authorized resume; accepted instructions remain queryable.
`ISSUANCE_DISABLED`	`409`	The campaign is not enabled for new issuance.	Complete the approved activation workflow.
`PROFILE_NOT_APPROVED`	`422`	The campaign asset profile is not approved for the operation.	Resolve the operator verification gate.
`RATE_LIMITED`	`429`	The project has exceeded its request allowance.	Respect Retry-After, reduce concurrency, and retry the same instruction.
`TEMPORARILY_UNAVAILABLE`	`503`	The service cannot currently complete the operation reliably.	Back off; preserve the same idempotency key for a write.
`INTERNAL_ERROR`	`500`	An unexpected server failure occurred.	Retain the request ID and treat write outcome as uncertain; recover using the original identity.

Safe recovery from an uncertain write#

Network timeouts, aborted requests, and upstream failures do not establish whether the server accepted the instruction. Keep the original event, recipient, amount, and key. Replay that instruction or retrieve the known reward before taking another economic action.

A DUPLICATE_EVENT response is not automatically equivalent to success for your current input. Read the existing record and compare all immutable fields first.

A failed cancellation likewise does not prove that a reward was cancelled. Verify its current state before issuing a replacement.

HTTP and SDK errors#

The SDK represents structured API failures as SlicesApiError, exposing status, code, requestId, and optional existingRewardId. Transport failures and local cancellation may be ordinary errors without a server response or request ID.

An infrastructure proxy can return an HTML or otherwise nonstandard 502, 503, or 504 response. Your integration should handle that as a transport/service failure rather than assuming every unsuccessful response parses as the Slices JSON envelope.

The automatic retry policy covers bounded transient network failures and 429, 502, 503, and 504. It does not automatically retry validation, authorization, conflicts, or every generic 500. See Rate limits and retries.

Record the request ID, operation, approximate timestamp, environment, and affected reward or campaign ID. Keep keys, full request bodies containing sensitive data, and wallet material out of logs and support messages.

The X-Request-Id header identifies the request even on successful responses. Include it when reporting a suspected inconsistency between acceptance and a later read.

Related: Idempotency, Troubleshooting, and API overview.

Errors

Error codes#

Safe recovery from an uncertain write#

HTTP and SDK errors#

Sharing diagnostics#