Error Codes Reference

Every AfriRoute API error returns a consistent JSON envelope with a machine-readable code, a human-readable message, and a request_id you can quote to support. This page lists the standard HTTP statuses and the full catalog of error codes.

📦 Error Envelope

{
  "success": false,
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must be in E.164 format",
    "details": "Received '0911234567', expected '+251911234567'",
    "request_id": "req_xyz789",
    "timestamp": "2026-05-10T12:30:00Z"
  }
}

Always log request_id — it lets support trace a single request end to end.

🚦 HTTP Status Codes

Code	Status	Meaning
200	OK	Request succeeded
201	Created	Resource created
400	Bad Request	Malformed request or invalid parameter
401	Unauthorized	Missing or invalid API key
403	Forbidden	Key lacks permission for this resource
404	Not Found	Resource does not exist
409	Conflict	Resource state conflict (e.g. duplicate)
413	Payload Too Large	Uploaded media exceeds the limit
422	Unprocessable Entity	Validation failed
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error
503	Service Unavailable	Dependency temporarily unavailable

🔑 Authentication & Authorization

Code	HTTP	Description
MISSING_API_KEY	401	No Authorization header supplied
INVALID_API_KEY	401	Key is malformed, revoked, or unknown
EXPIRED_TOKEN	401	Bearer token has expired
FORBIDDEN_SCOPE	403	Key not authorized for this endpoint
IP_NOT_ALLOWED	403	Request IP not in the allowlist

⏱️ Rate Limiting & Quotas

Code	HTTP	Description
RATE_LIMIT_EXCEEDED	429	Too many requests; see Retry-After header
QUOTA_EXCEEDED	429	Monthly plan quota reached
INSUFFICIENT_BALANCE	402	Wallet balance too low to complete the action

✉️ Messaging (SMS / Voice / Email)

Code	HTTP	Description
INVALID_PHONE	400	Number is not valid E.164
INVALID_SENDER_ID	400	Sender ID not registered or malformed
MESSAGE_TOO_LONG	422	Message exceeds the segment limit
UNDELIVERABLE	422	Carrier could not deliver
UNSUPPORTED_COUNTRY	422	Destination country not supported

💰 Payments

Code	HTTP	Description
INSUFFICIENT_FUNDS	422	Payer has insufficient funds
PAYMENT_DECLINED	422	Provider declined the transaction
INVALID_AMOUNT	400	Amount is zero, negative, or unsupported
DUPLICATE_TRANSACTION	409	A transaction with this reference already exists
PROVIDER_UNAVAILABLE	503	Mobile-money provider temporarily down

🪪 Identity Verification

Code	HTTP	Description
INVALID_DOCUMENT_TYPE	400	Unsupported document_type for the country
IMAGE_QUALITY_LOW	422	Image too blurry, dark, or cropped
NO_FACE_DETECTED	422	No face found in the supplied image
MULTIPLE_FACES	422	More than one face detected
FACE_MISMATCH	422	Selfie does not match the document photo
LIVENESS_FAILED	422	Presentation attack detected
DOCUMENT_EXPIRED	422	Document past its expiry date
OTP_EXPIRED	422	OTP code has expired
OTP_INVALID	422	OTP code does not match
OTP_MAX_ATTEMPTS	429	Too many OTP attempts
REGISTRY_UNAVAILABLE	503	Government registry (BVN/Fayda/Ghana Card) unreachable

🔔 Webhooks

Code	HTTP	Description
INVALID_URL	400	Webhook URL is not valid HTTPS
INVALID_EVENT	400	Unknown event type in subscription
WEBHOOK_NOT_FOUND	404	No webhook with that ID
WEBHOOK_LIMIT_REACHED	422	Plan webhook limit exceeded
WEBHOOK_TIMEOUT	—	Delivery timed out (>10s)
WEBHOOK_EXHAUSTED	—	All retry attempts failed

🛠️ Handling Errors (JavaScript)

const res = await fetch(url, options);
if (!res.ok) {
  const { error } = await res.json();
  switch (error.code) {
    case 'RATE_LIMIT_EXCEEDED':
      await backoff(res.headers.get('Retry-After'));
      break;
    case 'INSUFFICIENT_BALANCE':
      notifyBilling();
      break;
    default:
      logError(error.request_id, error.message);
  }
}

📚 Related Resources

• Troubleshooting Guide
• Common Issues
• API Reference
• Retry Logic

---

Last Updated: May 2026 | Need help? [email protected]