All Simiz API errors follow a consistent format. This page documents every error code and how to resolve them.
{
"error": {
"code": "insufficient_balance",
"message": "Customer has insufficient balance",
"type": "payment_error",
"http_status": 400,
"request_id": "req_abc123"
}
}
| Field | Description |
|---|
code | Machine-readable error code |
message | Human-readable description |
type | Error category |
http_status | HTTP status code |
request_id | Unique request ID for debugging |
Authentication errors
| Code | HTTP | Description | Solution |
|---|
invalid_api_key | 401 | The API key is invalid or doesn’t exist | Check you’re using the correct key (test vs live) |
expired_api_key | 401 | The API key has expired | Regenerate a key from your Dashboard |
insufficient_permissions | 403 | The key doesn’t have the required permissions | Check key permissions or contact support |
Payment errors
| Code | HTTP | Description | Solution |
|---|
insufficient_balance | 400 | Customer’s wallet balance is too low | Inform customer to top up their wallet |
invalid_phone | 400 | Phone number is invalid or doesn’t match the provider | Validate the format (e.g., 237XXXXXXXXX) |
transaction_limit | 400 | Transaction exceeds daily/monthly limit | Split the payment or wait for limit reset |
payment_expired | 400 | Payment confirmation timeout (15 min) | Create a new payment |
payment_cancelled | 400 | Customer cancelled the payment | Offer the customer to retry |
duplicate_transaction | 409 | A transaction with this reference already exists | Use a unique idempotency key |
Validation errors
| Code | HTTP | Description | Solution |
|---|
invalid_amount | 400 | Amount is outside allowed range | Ensure amount is between 100 and 5,000,000 |
invalid_currency | 400 | Currency is not supported | Use XAF or XOF |
missing_required_field | 400 | A required field is missing | Check all required fields are included |
invalid_email | 400 | Email format is invalid | Validate email format |
Provider errors
| Code | HTTP | Description | Solution |
|---|
provider_unavailable | 503 | Mobile Money provider is down | Retry after a few minutes |
provider_timeout | 504 | Provider didn’t respond in time | Retry the transaction |
pin_error | 400 | Customer entered the wrong PIN | Customer should retry with correct PIN |
account_inactive | 400 | Customer’s mobile wallet is inactive | Customer should contact their operator |
service_suspended | 403 | Provider’s service is temporarily suspended | Contact support |
Rate limiting errors
| Code | HTTP | Description | Solution |
|---|
rate_limit_exceeded | 429 | API rate limit exceeded | Wait and retry with exponential backoff |
too_many_requests | 429 | Too many requests in a short period | Implement backoff, see Rate Limiting |
Internal errors
| Code | HTTP | Description | Solution |
|---|
internal_error | 500 | An internal server error occurred | Retry the request. Contact support if persistent |
service_unavailable | 503 | Simiz is temporarily unavailable | Retry after a few minutes |
HTTP status codes reference
| Code | Name | Description |
|---|
200 | OK | Request succeeded |
201 | Created | Resource created successfully |
400 | Bad Request | Invalid parameters |
401 | Unauthorized | Authentication required |
403 | Forbidden | Insufficient permissions |
404 | Not Found | Resource not found |
409 | Conflict | Duplicate entry |
429 | Too Many Requests | Rate limit exceeded |
500 | Internal Server Error | Server error — retry |
503 | Service Unavailable | Temporarily down |
504 | Gateway Timeout | Provider timeout |
Error handling example
# Create a payment and handle errors based on HTTP status code
response=$(curl -s -w "\n%{http_code}" -X POST https://api.simiz.io/v1/transactions \
-H "Authorization: Bearer sk_test_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"amount": 5000,
"currency": "XAF",
"payment_method": "ORANGE_MONEY",
"payer": { "phone": "237690000001", "name": "John Doe" },
"description": "Order #12345"
}')
http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | head -1)
case $http_code in
201) echo "Payment created: $body" ;;
400) echo "Validation error: $body" ;;
401) echo "Invalid API key" ;;
429) echo "Rate limited — retry later" ;;
5*) echo "Server error — retry" ;;
esac
Include the request_id when contacting support — it helps us debug your issue faster.
