Error Handling
Best practices for handling API errors.
Error Handling
Error Response Format
json
{
"error": "Human readable message",
"code": "MACHINE_READABLE_CODE",
"details": { }
}Common Error Codes
| Code | HTTP Status | Description |
|---|---|---|
UNAUTHORIZED | 401 | Invalid or missing API key |
FORBIDDEN | 403 | Key lacks required scope |
INSUFFICIENT_BALANCE | 402 | Not enough tokens |
NOT_FOUND | 404 | Resource doesn't exist |
RATE_LIMITED | 429 | Too many requests |
VALIDATION_ERROR | 400 | Invalid request parameters |
MODEL_ERROR | 500 | Model execution failed |
Handling Examples
typescript
async function runModel(modelId: string, input: object) {
const response = await fetch(`/api/v1/models/${modelId}/run`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ input })
});
if (!response.ok) {
const error = await response.json();
switch (response.status) {
case 401:
throw new Error('Invalid API key');
case 402:
throw new Error('Insufficient tokens. Please top up.');
case 429:
const retryAfter = response.headers.get('Retry-After');
throw new Error(`Rate limited. Retry in ${retryAfter}s`);
default:
throw new Error(error.message || 'Unknown error');
}
}
return response.json();
}