Error Handling

The Bitrefill API uses standard HTTP status codes and provides detailed error messages. This guide explains how to handle errors effectively.

Error Response Format

Error responses follow this structure:

{
  "meta": {
    "_endpoint": "/invoices"
  },
  "message": "Human-readable error description",
  "error_code": "machine_readable_code"
}

message — Explains what went wrong
error_code — Consistent code for programmatic handling

HTTP Status Codes

Code	Meaning	Common Causes
400	Bad Request	Invalid parameters
401	Unauthorized	Missing or invalid auth
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal error

Handling Errors

async function apiRequest(url, options) {
  const response = await fetch(url, options);
  const data = await response.json();
  
  if (!response.ok) {
    const error = new Error(data.message || 'API Error');
    error.code = data.error_code;
    error.status = response.status;
    throw error;
  }
  
  return data;
}

// Usage
try {
  const invoice = await apiRequest('/invoices', { method: 'POST', ... });
} catch (error) {
  switch (error.code) {
    case 'balance_too_low':
      console.log('Need to add balance');
      break;
    case 'out_of_stock':
      console.log('Product unavailable');
      break;
    default:
      console.log(`Error: ${error.message}`);
  }
}

Error Guides

Error Codes

Complete error code reference

Troubleshooting

Common issues and solutions

Quick Reference

Authentication Errors

Code	Message	Solution
401	Unauthorized	Check API credentials
403	Forbidden	Verify account permissions

Invoice Errors

Error Code	Message	Solution
`balance_too_low`	Insufficient balance	Add funds
`out_of_stock`	Product unavailable	Try different product
`not_found`	Product doesn't exist	Check product ID
`invalid_param`	Invalid parameter	Check request format
`too_many_items`	Too many items	Max 20 per invoice

Rate Limit Errors

Code	Message	Solution
429	Rate limit exceeded	Wait and retry

Check X-RateLimit-Reset header for when to retry.