The Bags API uses standardized error responses to help you handle issues in your applications.
All errors return JSON with a consistent structure:
{
"success": false,
"error": "Detailed error message"
}
{
"success": true,
"response": {
// Response data here
}
}
Common Status Codes
| Status Code | Description | When It Occurs |
|---|
| 400 | Bad Request | Invalid request parameters or validation errors |
| 401 | Unauthorized | Missing or invalid API key/authentication |
| 403 | Forbidden | Valid authentication but insufficient permissions |
| 404 | Not Found | Resource not found |
| 413 | Payload Too Large | File upload exceeds size limit |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Unexpected server error |
Error Examples
Validation Error (400)
{
"success": false,
"error": "Token name is required and must be between 1-32 characters"
}
Authentication Error (401)
{
"success": false,
"error": "Invalid API key. Please check your x-api-key header."
}
Permission Error (403)
{
"success": false,
"error": "API key does not have permission to access this resource"
}
Rate Limit Error (429)
When you exceed rate limits, the API returns additional information:
{
"success": false,
"error": "Rate limit exceeded",
"limit": 1000,
"remaining": 0,
"resetTime": 1672531200
}
File Upload Error (413)
{
"success": false,
"error": "Image file must be under 15MB"
}
Server Error (500)
{
"success": false,
"error": "An unexpected error occurred. Please try again later."
}
Best Practices
Error Handling in Code
try {
const response = await fetch('https://public-api-v2.bags.fm/api/v1/endpoint', {
headers: { 'x-api-key': 'YOUR_API_KEY' }
});
const data = await response.json();
if (!data.success) {
console.error('API Error:', data.error);
// Handle specific error cases
switch (response.status) {
case 401:
// Redirect to login or refresh API key
break;
case 429:
// Implement exponential backoff
break;
default:
// Generic error handling
}
return;
}
// Process successful response
console.log(data.response);
} catch (error) {
console.error('Network error:', error);
}
Retry Logic
Implement exponential backoff for rate limit and server errors:
- 429 (Rate Limited): Wait based on
resetTime or implement exponential backoff
- 500/502/503: Retry with exponential backoff (max 5 attempts)
- 400/401/403/404: Don’t retry - fix the request first
Check the X-RateLimit-* headers to proactively avoid rate limits rather than handling them reactively.
