Error Handling and Troubleshooting
Handle common errors, understand rate limits, and debug issues in your Novisurf API integrations.
{
"error": {
"message": "Rate limit exceeded. Retry after 30s.",
"type": "rate_limit",
"retry_after": 30
}
}
Common HTTP Error Codes
Novisurf API returns standard HTTP status codes. Use these to identify issues quickly.
| Status Code | Meaning | Common Causes |
|---|---|---|
| 400 | Bad Request | Invalid JSON, missing parameters |
| 401 | Unauthorized | Missing or invalid {API_KEY} |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Invalid endpoint or model |
| 429 | Rate Limited | Exceeded rate limits |
| 500 | Internal Server Error | Server-side issue |
Always check the error object in responses for detailed messages.
Rate Limit Responses and Mitigation
Rate limits protect the API from abuse. Exceeding them returns a 429 response.
Check Headers
Inspect x-ratelimit-remaining and x-ratelimit-reset headers in responses.
Implement Retry Logic
Use exponential backoff with jitter.
Monitor Usage
Track requests in your dashboard at https://dashboard.example.com/usage.
Debugging Failed Requests
Follow these steps to diagnose API failures.
import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';
const openai = createOpenAI({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://api.example.com/v1',
});
try {
const { text } = await generateText({
model: openai('gpt-4o-mini'),
prompt: 'Explain quantum computing.',
});
console.log(text);
} catch (error) {
console.error('Error:', error.message);
console.error('Status:', error.status);
}
import axios from 'axios';
try {
const response = await axios.post('https://api.example.com/v1/chat/completions', {
model: 'gpt-4o-mini',
messages: [{ role: 'user', content: 'Hello' }],
}, {
headers: { Authorization: `Bearer YOUR_API_KEY` },
});
} catch (error) {
if (error.response) {
console.error('Status:', error.response.status);
console.error('Data:', error.response.data);
}
}
import openai
client = openai.OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.example.com/v1",
)
try:
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)
except openai.APIError as e:
print(f"Error: {e}")
Logging and Monitoring Tips
Enable detailed logging to capture errors effectively.
Use Structured Logging
Log request ID, status, and response body for easy searching.
Integrate Monitoring
Connect to tools like Datadog or Sentry for alerts.
Create reusable handlers for common errors.
function handleAPIError(error) {
if (error.status === 429) {
// Implement backoff
return retryWithBackoff(error.request);
}
if (error.status === 401) {
// Refresh token
return refreshAuthAndRetry();
}
throw error;
}
Never log sensitive data like full {API_KEY} or user payloads.
Next Steps
Last updated today
Built with Documentation.AI