Error handling

All Crycket API errors return a consistent envelope. Use the HTTP status code as the primary signal and the code field for machine-readable error identification.

Error format

{
  "error": {
    "code": "intent.already_fulfilled",
    "message": "This payment intent has already been fulfilled.",
    "param": null,
    "details": {
      "intent_id": "pi_abc123",
      "current_state": "confirmed"
    }
  }
}

Field	Description
`code`	Machine-readable error code in `resource.error_type` dot notation
`message`	Human-readable error message
`param`	Field name if this is a validation error
`details`	Additional context about the error

HTTP status codes

Status	Meaning
400	Malformed request or validation error
401	Invalid or missing API key
402	Feature requires a higher plan tier
404	Resource not found
409	Conflict — wrong state for this operation
422	Semantically invalid (e.g. token not available on this chain)
503	RPC upstream unavailable — includes `retry_after`

Common error scenarios

State conflicts (409)

Returned when you try an operation that isn’t valid for the intent’s current state:

Cancelling an intent that isn’t in created state
Building a transaction for an already-confirmed intent
Submitting to an expired intent

Always check the intent’s current state before performing operations.

Stale updates (409)

PATCH /v1/intents/:id requires the current updatedAt timestamp for optimistic concurrency. If another update happened between your read and write, you get a 409. Re-fetch the intent and retry with the fresh updatedAt.

RPC unavailable (503)

Returned when the upstream RPC provider is unreachable during transaction submission. The response includes a retry_after value. Implement retry with exponential backoff.

Sanctions screening (422)

Every POST /v1/intents and POST /v1/intents/:id/submit screens wallet addresses against the OFAC SDN list. If the screening API is unavailable, the request is rejected with 503 (fail closed). A match returns 422 with error.code: "address.sanctions_match".

Getting started

Core concepts

Integration guides

SDK

Error format

HTTP status codes

Common error scenarios

State conflicts (409)

Stale updates (409)

RPC unavailable (503)

Sanctions screening (422)

​Error format

​HTTP status codes

​Common error scenarios

​State conflicts (409)

​Stale updates (409)

​RPC unavailable (503)

​Sanctions screening (422)

Error format

HTTP status codes

Common error scenarios

State conflicts (409)

Stale updates (409)

RPC unavailable (503)

Sanctions screening (422)