Errors & Rate Limits
Error format
{
"status": "error",
"code": "INVALID_PHONE",
"message": "The recipient phone number is not valid E.164 format.",
"details": {
"field": "recipient_phone",
"value": "0501234567"
}
}
Common error codes
| Code | HTTP | Description |
|---|---|---|
UNAUTHORIZED | 401 | Missing or invalid API key |
MISSING_PARAMS | 400 | Required field missing |
INVALID_CURRENCY | 400 | Use USDT or USDC for withdrawals |
INVALID_AMOUNT | 400 | Invalid amount format |
INVALID_PHONE | 400 | Phone must be +233 + 9 digits |
INVALID_NETWORK | 400 | Use MTN, TELECEL, or AIRTELTIGO |
MISSING_REFERENCE | 400 | reference_id required on withdrawals |
BELOW_MINIMUM | 422 | Below network minimum |
ABOVE_MAXIMUM | 422 | Above network or tier maximum |
NOT_FOUND | 404 | Resource not found |
INVALID_STATE | 409 | Invalid state transition (e.g. cancel non-pending intent) |
VALIDATION_ERROR | 400 | Schema validation failed |
INTERNAL_ERROR | 500 | Server error — retry with backoff |
Retry guidance
| Situation | Action |
|---|---|
4xx (except 429) | Fix the request — do not retry blindly |
429 | Retry after Retry-After |
5xx / timeout | Retry with exponential backoff; reuse same reference_id |
Rate limits
| Plan | Requests/min | Requests/day |
|---|---|---|
| Sandbox | 60 | 10,000 |
| Production | 300 | 100,000 |
Contact partners@fiatsend.com for higher limits.