Error Codes

This page documents all error codes returned by the Bitrefill API.

Invoice Creation Errors

Errors when creating invoices via POST /invoices or POST /esims:

Error Code	Description	Solution
`unsupported_payment_method`	Payment method not supported	Use: `balance`, `bitcoin`, `lightning`, `ethereum`, etc.
`missing_param`	Required parameter missing	Check the `message` for which parameter
`parse_error`	Failed to parse request	Verify JSON structure
`not_found`	Product doesn't exist	Verify product ID is correct
`out_of_stock`	Product unavailable	Try later or different product
`invalid_param`	Parameter has wrong type	Check the `message` for details
`too_many_items`	More than 20 items	Split into multiple invoices
`create_invoice_failed`	Internal error	Contact support if persistent
`balance_too_low`	Insufficient balance	Add funds or use crypto

Examples

Missing parameter:

{
  "error_code": "missing_param",
  "message": "Missing required parameter: product_id"
}

Out of stock:

{
  "error_code": "out_of_stock",
  "message": "Product 'amazon-us' is currently out of stock"
}

Balance too low:

{
  "error_code": "balance_too_low",
  "message": "Insufficient balance. Required: $50.00, Available: $25.00"
}

Authentication Errors

HTTP Code	Error	Solution
401	Unauthorized	Verify API key/credentials
403	Forbidden	Check account permissions

Common Causes

401 Unauthorized:

Wrong API key
Malformed Authorization header
Expired or revoked credentials
Using Bearer when Basic is required (or vice versa)

403 Forbidden:

Account doesn't have API access
Trying to access affiliate-only endpoints
Account suspended

Rate Limit Errors

HTTP Code	Error	Solution
429	Too Many Requests	Wait and retry

Response headers indicate limits:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704067200

Wait until X-RateLimit-Reset (Unix timestamp) to retry.

Order/Delivery Errors

Order-level errors appear in the order object:

{
  "id": "ord_xyz789",
  "status": "failed",
  "error": "Provider temporarily unavailable"
}

Status	Meaning	Action
`failed`	Delivery failed	Automatic refund usually
`refunded`	Payment returned	Check balance/refund address

Validation Errors

Error Code	Description	Solution
`invalid_phone_number`	Phone number invalid	Use E.164 format (+15551234567)
`unsupported_operator`	Operator not supported	Check with `/check_phone_number`
`invalid_value`	Value outside allowed range	Check product `range` or `packages`
`invalid_package_id`	Package ID doesn't exist	Verify against product details
`invalid_quantity`	Quantity invalid	Use positive integer

BRGC Batch Errors

Error Code	Description	Solution
`batch_creation_failed`	Failed to create batch	Contact support
`invalid_quantity`	Invalid batch size	Check limits
`invalid_currency`	Currency not supported	Use USD, EUR, etc.

Handling Unknown Errors

For undocumented error codes:

Log the full error response
Check the message for details
If persistent, contact support with:
- Error code and message
- Request body (without sensitive data)
- Timestamp

Error Handling Best Practices

async function safeApiCall(url, options) {
  try {
    const response = await fetch(url, options);
    const data = await response.json();
    
    if (!response.ok) {
      // Handle known errors
      switch (data.error_code) {
        case 'balance_too_low':
          return { success: false, error: 'insufficient_balance' };
        case 'out_of_stock':
          return { success: false, error: 'unavailable' };
        case 'not_found':
          return { success: false, error: 'product_not_found' };
        default:
          // Log unknown errors
          console.error('Unknown error:', data);
          return { success: false, error: 'unknown', details: data };
      }
    }
    
    return { success: true, data: data.data };
    
  } catch (networkError) {
    // Handle network errors
    console.error('Network error:', networkError);
    return { success: false, error: 'network_error' };
  }
}