Error Handling

Understanding API error responses and status codes

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 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

Node.js

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.