Error Handling | Levrage.AI | API Documentation

Every API response follows a consistent envelope. When something goes wrong, you’ll get a clear error with an actionable message.

Error Response Format

1 {
2   "success": false,
3   "error": {
4     "code": "validation_error",
5     "message": "Agent name is already in use"
6   },
7   "request_id": "req_abc123",
8   "timestamp": "2025-01-01T12:00:00Z"
9 }

Always log the request_id — our support team can use it to trace any issue instantly.

HTTP Status Codes

Client Errors (4xx)

Code	Name	When It Happens
`400`	Bad Request	Malformed JSON, missing required fields
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	API key lacks permission for this resource
`404`	Not Found	Agent, campaign, or call doesn’t exist
`409`	Conflict	Duplicate resource (e.g., agent name already taken)
`422`	Validation Error	Fields present but invalid values
`429`	Rate Limited	Too many requests — back off and retry

Server Errors (5xx)

Code	Name	When It Happens
`500`	Internal Error	Unexpected server error — safe to retry
`502`	Bad Gateway	Upstream service temporarily unavailable
`503`	Service Unavailable	System under maintenance
`504`	Gateway Timeout	Request took too long — retry with backoff

Rate Limiting

Rate limits depend on your plan:

Plan	Requests/Minute
Free	60
Pro	300
Enterprise	Custom

When you hit the limit, you’ll get a 429 response with these headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706140800

Exceeding rate limits repeatedly may result in temporary IP-level throttling. Always implement exponential backoff.

Retry Strategy

Not all errors should be retried. Follow this guide:

Status	Retry?	Strategy
`400`	No	Fix the request
`401`	No	Check your API key
`404`	No	Verify the resource ID
`422`	No	Fix validation errors
`429`	Yes	Wait for `X-RateLimit-Reset`, then retry
`500`	Yes	Retry with exponential backoff
`502`	Yes	Retry after 1-2 seconds
`503`	Yes	Wait 30+ seconds, then retry
`504`	Yes	Retry with longer timeout

Code Examples

1 import requests
2 import time
3 
4 def api_call_with_retry(method, url, headers, json=None, max_retries=3):
5     """Make an API call with automatic retry on transient errors."""
6     for attempt in range(max_retries):
7         response = requests.request(method, url, headers=headers, json=json)
8 
9         if response.status_code == 200:
10             return response.json()
11 
12         if response.status_code == 429:
13             # Rate limited — wait for reset
14             reset_time = int(response.headers.get("X-RateLimit-Reset", 0))
15             wait = max(reset_time - int(time.time()), 1)
16             print(f"Rate limited. Waiting {wait}s...")
17             time.sleep(wait)
18             continue
19 
20         if response.status_code >= 500:
21             # Server error — exponential backoff
22             wait = (2 ** attempt) + 0.5
23             print(f"Server error {response.status_code}. Retrying in {wait}s...")
24             time.sleep(wait)
25             continue
26 
27         # Client error — don't retry
28         error = response.json()
29         raise Exception(f"API Error {response.status_code}: {error}")
30 
31     raise Exception("Max retries exceeded")

Common Errors & Fixes

Error Code	Message	Fix
`validation_error`	”Agent name is already in use”	Choose a unique agent name
`validation_error`	”phone_number must be E.164 format”	Use format `+919876543210`
`not_found`	”Agent not found”	Verify the agent ID exists
`authentication_error`	”Invalid or expired API key”	Regenerate your API key in the Dashboard
`quota_exceeded`	”Insufficient credits”	Top up credits in the Dashboard