Error Codes

Common Error Codes (All APIs)

Code	Description	Resolution
AUTHENTICATION_FAILED	Invalid or missing API key/token	Check authentication headers
AUTHORIZATION_DENIED	Insufficient permissions	Verify user permissions
VALIDATION_ERROR	Invalid request parameters	Check request format and required fields
RATE_LIMIT_EXCEEDED	Too many requests	Implement rate limiting and retry logic
INTERNAL_ERROR	Server-side error	Retry request or contact support
NETWORK_TIMEOUT	Request timeout	Implement retry with exponential backoff

Datastore-Specific Errors

Code	Description	Resolution
COLLECTION_NOT_FOUND	Collection doesn't exist	Verify collection name
DOCUMENT_NOT_FOUND	Document doesn't exist	Check document key
INVALID_QUERY	Malformed QLO query	Validate query syntax
DUPLICATE_KEY	Document key already exists	Use unique keys or upsert operation
QUOTA_EXCEEDED	Storage/operation quota reached	Review usage or upgrade plan

Auth-Specific Errors

Code	Description	Resolution
INVALID_CREDENTIALS	Wrong email/password	Verify credentials
OTP_EXPIRED	OTP code expired	Request new OTP
OTP_INVALID	Incorrect OTP code	Check OTP and retry
EMAIL_ALREADY_EXISTS	Email is registered	Use different email or sign in
TOKEN_EXPIRED	JWT token expired	Refresh token or re-authenticate
WEAK_PASSWORD	Password doesn't meet policy	Use stronger password
EMAIL_NOT_VERIFIED	Email verification required	Verify email address

Storage-Specific Errors

Code	Description	Resolution
FILE_NOT_FOUND	File doesn't exist	Verify file key
FILE_TOO_LARGE	File exceeds size limit	Reduce file size
INVALID_FILE_TYPE	Unsupported file format	Use supported file types
UPLOAD_EXPIRED	Presigned URL expired	Generate new presigned URL
PROCESSING_FAILED	Image processing failed	Check image format and retry
STORAGE_QUOTA_EXCEEDED	Storage limit reached	Clean up files or upgrade plan

Error Handling Best Practices

Retry Logic

async function apiRequestWithRetry(requestData, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch('https://cloud.singlebaseapis.com/api/$PROJECT-ID', {
        method: 'POST',
        headers: {
          'X-API-KEY': 'your-api-key',
          'Authorization': 'Bearer your-token',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(requestData)
      });

      if (!response.ok) {
        const error = await response.json();
        
        // Don't retry for client errors
        if (response.status >= 400 && response.status < 500) {
          throw new Error(error.error.message);
        }
        
        // Retry for server errors
        if (attempt === maxRetries) {
          throw new Error(`Max retries reached: ${error.error.message}`);
        }
        
        // Exponential backoff
        await new Promise(resolve => 
          setTimeout(resolve, Math.pow(2, attempt) * 1000)
        );
        continue;
      }

      return await response.json();
    } catch (error) {
      if (attempt === maxRetries) throw error;
    }
  }
}

Error Response Handling

function handleApiError(error) {
  switch (error.error.code) {
    case 'AUTHENTICATION_FAILED':
      // Redirect to login
      redirectToLogin();
      break;
    case 'TOKEN_EXPIRED':
      // Attempt token refresh
      refreshAuthToken();
      break;
    case 'VALIDATION_ERROR':
      // Show validation errors to user
      showValidationErrors(error.error.details);
      break;
    case 'RATE_LIMIT_EXCEEDED':
      // Implement exponential backoff
      scheduleRetry(error.error.details.retry_after);
      break;
    default:
      // Generic error handling
      showErrorMessage(error.error.message);
  }
}