Home / Documentation / error-handling

Error Handling Reference

Understand, catch, and gracefully recover from API errors. Built for resilience at scale.

HTTP Status Codes

400 Bad Request

Malformed syntax, invalid parameters, or missing required fields. Check payload structure.

401 Unauthorized

Missing or invalid API key. Verify your authentication header: `Authorization: Bearer <key>`.

429 Rate Limited

Too many requests. Implement exponential backoff. Check `Retry-After` header.

500 Server Error

Unexpected internal failure. Our systems self-heal. Retry with jitter after 5-15s.

503 Service Unavailable

Model overload or scheduled maintenance. Monitor status page before retrying.

200 Success

Request processed successfully. Response body contains model output & metadata.

Implementation Examples

async function callNexusAI(prompt) {
try {
const res = await fetch('https://api.nexusai.com/v3/generate', {
method: 'POST',
headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ prompt, model: 'nexus-v3-ultra' })
});
if (!res.ok) {
const err = await res.json();
throw new Error(`[${res.status}] ${err.message}`);
}
return await res.json();
} catch (error) {
// Handle 429 with exponential backoff
if (error.message.includes('429')) await retryWithBackoff(error);
else console.error('NexusAI Error:', error);
}
}
import requests, time, random
def nexus_generate(prompt, max_retries=3):
for attempt in range(max_retries):
try:
response = requests.post(
"https://api.nexusai.com/v3/generate",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"prompt": prompt, "model": "nexus-v3-ultra"}
)
response.raise_for_status()
return response.json()
except requests.exceptions.HTTPError as e:
if response.status_code == 429:
delay = 2 ** attempt + random.uniform(0, 1)
print(f"Rate limited. Retrying in {delay:.1f}s")
time.sleep(delay)
continue
raise
curl -X POST https://api.nexusai.com/v3/generate \
-H "Authorization: Bearer $NEXUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "Summarize this report", "model": "nexus-v3-ultra"}' \
--fail-with-body

Live Error Simulator

Test how your implementation handles common failure scenarios.

nexus-debug-console
> Initializing NexusAI error simulation...
> [429] RateLimitExceeded: Requests exceed quota. Retry-After: 3s
> Applying exponential backoff (attempt 1/3)...
> Connection restored. Payload validated.
> Simulation complete. Check your client-side retry logic.

Best Practices

🔄

Implement Retry with Jitter

Never retry immediately. Use exponential backoff + random jitter to prevent thundering herd effects.

🛡️

Circuit Breakers

Wrap API calls in circuit breaker patterns. Fail fast when downstream models are degraded.

📦

Idempotent Requests

Use idempotency keys for write operations. Prevents duplicate charges or state corruption on retries.

📊

Structured Logging

Log error codes, request IDs, and payloads. NexusAI includes `x-request-id` for trace correlation.