Skip to main content
All Cherp 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"
    }
  }
}
FieldDescription
codeMachine-readable error code in resource.error_type dot notation
messageHuman-readable error message
paramField name if this is a validation error
detailsAdditional context about the error

​
HTTP status codes

StatusMeaning
400Malformed request or validation error
401Invalid or missing API key
402Feature requires a higher plan tier
404Resource not found
409Conflict — wrong state for this operation
422Semantically invalid (e.g. token not available on this chain)
503RPC 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".