The Bags API uses standardized error responses to help you handle issues in your applications.

​
Error Response Format

All errors return JSON with a consistent structure: 
{
  "success": false,
  "error": "Detailed error message"
}
Success responses use a different format: 
{
  "success": true,
  "response": {
    // Response data here
  }
}

​
Common Status Codes

Status CodeDescriptionWhen It Occurs
400Bad RequestInvalid request parameters or validation errors
401UnauthorizedMissing or invalid API key/authentication
403ForbiddenValid authentication but insufficient permissions
404Not FoundResource not found
413Payload Too LargeFile upload exceeds size limit
429Too Many RequestsRate limit exceeded
500Internal Server ErrorUnexpected 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:
  1. 429 (Rate Limited): Wait based on resetTime or implement exponential backoff
  2. 500/502/503: Retry with exponential backoff (max 5 attempts)
  3. 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.