Error Handling

HTTP Status Codes

Code	Description
200	Success
202	Accepted — pending approval (antifraud)
400	Bad Request — invalid or missing parameters
401	Unauthorized — invalid or expired token
402	Invalid data
403	Forbidden — access denied or blocked by antifraud
404	Not Found
405	Method Not Allowed
429	Too Many Requests — rate limit exceeded
500	Internal Server Error
503	Service Unavailable

Error Response Format

{
  "status": "ERROR",
  "message": "Detailed error description",
  "when": 1710700000000
}

Common Errors

Error	Cause	Solution
Invalid token	Expired or revoked Bearer token	Re-authenticate via /access-token
Account not found	Invalid account ID or document	Verify account exists and is active
Insufficient funds	Account balance too low	Check balance before transfer
Duplicate transaction	Same Idempotency-Key reused	Use a new UUID
Rate limit exceeded	Too many requests	Implement exponential backoff
Tenant suspended	Billing issue on tenant	Contact support

---