Skip to main content
Most error responses use a flexible ErrorResponse payload. The exact fields can vary by handler, so integrations should parse defensively.

​
Common Error Shape

Every error response includes: 
{
  "status": "error"
}
Depending on the endpoint, the payload may also include:
  • error
  • reason
  • detail
  • field
  • currency
  • missing
  • errors
  • message
  • constraint
  • tx_status
  • project_uid
  • widget_id
  • expected

​
Typical Status Codes

CodeMeaningCommon Cases
400Invalid requestMissing fields, invalid ids, or redirect not available for the current state
403ForbiddenInvalid signature, inactive project, or wallet ownership failure
404Not foundProject, network, widget, or transaction does not exist
422Validation or processing failureProject creation failures or invalid transaction creation input
500Internal failureOn-chain status checker or backend processing error

​
Validation Errors

Some handlers return an errors object that maps field names to one or more messages. Plan for both patterns below: 
{
  "status": "error",
  "error": "invalid_request"
}

{
  "status": "error",
  "errors": {
    "amount": ["must be greater than zero"]
  }
}

​
Integration Recommendations

  • treat transaction ids and project ids as opaque values;
  • log both HTTP status and the full error body;
  • preserve raw request bodies for signed transaction debugging;
  • retry only when the failure mode is transient or operationally recoverable;
  • keep callback replay tooling available for downstream recovery.

​
Operational Checklist

  • validate networks and currencies before project creation;
  • store secret_key safely when a project is created;
  • cap paginated reads with limit and offset;
  • handle both success JSON and 302 redirect responses in your client code.