Skip to main content

​
Error envelope

Every error response has the same shape: 
{
  "success": false,
  "status": 400,
  "error": "Human-readable message"
}
Some errors include a code field for machine-readable routing: 
{
  "success": false,
  "status": 403,
  "error": "KYC limit exceeded for this transaction amount",
  "code": "KYC_LIMIT_EXCEEDED",
  "current_tier": 1,
  "limit": 50000
}

​
HTTP status codes

CodeMeaning
200Success
201Resource created
204Success, no body (e.g. mark-read)
400Validation failed — check the error field
401Missing or invalid Bearer token
403Forbidden — KYC limit, wrong role, self-escrow, etc.
404Resource not found or not accessible by this user
409Conflict — duplicate (e.g. phone already registered)
422Business rule violation — invalid state transition
429Rate limit exceeded (OTP endpoints)
500Internal server error

​
Common error codes

codeEndpointMeaning
KYC_LIMIT_EXCEEDEDescrow-create, wallet-withdrawTransaction exceeds user’s KYC tier limit
INVALID_OTPauth-verify, auth-reset-passwordOTP is wrong or expired
PHONE_EXISTSauth-signupPhone number already registered
INVALID_STATEMost escrow/dispute/milestone endpointsEntity is not in the required state for this operation
NOT_PARTICIPANTmessage-send, message-feedUser is not a participant in the conversation