Error Handling
Most API errors follow a consistent JSON structure; some endpoints include extra metadata like code or timestamp.
Error Response Structure
| Field | Description |
|---|---|
success |
boolean - Always false for errors |
error |
string - Human-readable error message |
error_code |
string - Machine-readable error code (optional) |
details |
object - Additional error context (optional) |
code |
integer - HTTP status code (optional, APIAuth endpoints) |
timestamp |
string - ISO 8601 timestamp (optional) |
Common Error Codes
MISSING_API_KEY
401
No API key provided
INVALID_API_KEY
401
API key is invalid or revoked
API_KEY_EXPIRED
401
API key has expired
ACCOUNT_NOT_VERIFIED
403
Email verification required to use API
USER_INACTIVE
403
Account is deactivated
SERVICE_NOT_PERMITTED
403
API key lacks required service permission
RATE_LIMIT_EXCEEDED
429
Per-minute request limit exceeded
INSUFFICIENT_SERVICE_BALANCE
402
Service wallet balance too low for fees
INSUFFICIENT_PAYMENT_BALANCE
402
Payment wallet balance too low
PERSONAL_KYC_VERIFICATION_REQUIRED
403
Account requires KYC verification
CHANNEL_KYC_VERIFICATION_REQUIRED
403
Payment channel requires KYC
TRANSACTION_QUALITY_BELOW_THRESHOLD
403
Transaction success rate below 10%
WALLET_ACTIVATION_REQUIRED
403
Wallet channel activation fee required
VALIDATION_ERROR
400
Request validation failed
INTERNAL_ERROR
500
Internal server error