Error Handling

Understand error responses and how to handle them.

Error Response Format

All errors follow a consistent JSON format:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable description"
  }
}

Error Codes

Authentication Errors

Code	Status	Description
unauthorized	401	Invalid or missing API key
forbidden	403	Valid key but action not permitted (e.g., wrong origin for public key)

Validation Errors

Code	Status	Description
bad_request	400	Invalid request parameters
not_found	404	Resource not found

Limit Errors

Code	Status	Description
file_too_large	413	File exceeds your plan’s max file size
storage_limit_exceeded	413	Storage quota exceeded
rate_limit_exceeded	429	Too many requests
api_key_limit_exceeded	403	Maximum API keys reached for your plan

Account Errors

Code	Status	Description
grace_period	403	Account is in grace period—uploads disabled

Server Errors

Code	Status	Description
internal_error	500	Unexpected server error

Handling Errors

JavaScript

const response = await fetch('https://api.stashfyle.com/v1/upload', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sk_live_xxx' },
  body: form
});

if (!response.ok) {
  const { error } = await response.json();

  switch (error.code) {
    case 'file_too_large':
      console.error('File is too large. Max size:', error.message);
      break;
    case 'storage_limit_exceeded':
      console.error('Storage full. Upgrade your plan or delete files.');
      break;
    case 'rate_limit_exceeded':
      // Retry after delay
      const retryAfter = response.headers.get('Retry-After');
      await sleep(retryAfter * 1000);
      break;
    default:
      console.error('Upload failed:', error.message);
  }
}

Rate Limit Headers

When rate limited (429), check these headers:

Header	Description
X-RateLimit-Limit	Requests allowed per window
X-RateLimit-Remaining	Requests remaining
X-RateLimit-Reset	Unix timestamp when window resets
Retry-After	Seconds to wait before retrying

Best Practices

Always check response status

Never assume a request succeeded. Check the HTTP status code before processing the response.

Implement exponential backoff

For rate limits and server errors, use exponential backoff with jitter to avoid thundering herd.

Log error codes

Log the error code (not just the message) for easier debugging and monitoring.

Handle grace period gracefully

If you receive grace_period, notify users to update their subscription.