Error Codes
A searchable reference for AfriRoute API errors, including recommended remediation steps. Each code includes its category, HTTP status, and a resolution hint.
Error response shape
{
"error": {
"code": 4001,
"message": "You have exceeded your rate limit.",
"resolution": "Wait 30 seconds and retry. Implement exponential backoff.",
"category": "rate_limit",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}Reference
Rate limits & retries →The API key provided is invalid or expired.
Your API key does not have permission for this operation.
Your API key has expired.
Your IP address is not in the allowlist.
The phone number format is invalid.
Message body exceeds maximum length.
One or more request parameters are invalid.
A required field is missing from the request.
The requested message does not exist.
The requested conversation does not exist.
The requested AI agent does not exist.
You have exceeded your rate limit.
Too many concurrent requests.
The destination carrier is temporarily unavailable.
Your account balance is insufficient for this operation.
An internal server error occurred.
The request timed out.
Message delivery failed: invalid or inactive phone number.
Message delivery failed: recipient has blocked sender.
Message blocked by carrier spam filter.
AI decision confidence below required threshold. Human review required.
Request blocked by governance policy.
The requested AI model is temporarily unavailable.
AI operations suspended by kill switch.
Recipient consent required before sending message.
Message sending blocked during quiet hours (9PM - 8AM local time).
Operation violates data residency policy.
Operation restricted by local regulations.
Handling patterns
const res = await fetch(url, { method: 'POST', headers, body });
if (!res.ok) {
const data = await res.json().catch(() => null);
const code = data?.error?.code;
if (res.status === 429 || code === 4001) {
const retryAfter = data?.error?.retry_after ?? 1;
await new Promise(r => setTimeout(r, retryAfter * 1000));
// retry…
}
throw new Error(data?.error?.message ?? 'Request failed (' + res.status + ')');
}import time
import requests
res = requests.post(url, headers=headers, json=payload, timeout=15)
if res.status_code >= 400:
data = {}
try:
data = res.json()
except Exception:
pass
if res.status_code == 429 or data.get('error', {}).get('code') == 4001:
retry_after = data.get('error', {}).get('retry_after', 1)
time.sleep(retry_after)
# retry…
raise Exception(data.get('error', {}).get('message', f"Request failed ({res.status_code})"))