Skip to main content
Helicone AI Gateway automatically tries multiple billing methods to ensure your requests succeed. When one method fails, it falls back to alternatives and returns the most actionable error to help you fix issues quickly.

​
How Fallback Works

The AI Gateway supports two billing methods:

Pass-Through Billing (PTB)

Pay-as-you-go with Helicone credits. Simple, no provider account needed.

Bring Your Own Keys (BYOK)

Use your own provider API keys. You’re billed directly by the provider.
Automatic Fallback: When you configure both methods, the gateway tries PTB first. If it fails (e.g., insufficient credits), it automatically falls back to BYOK.

​
Error Priority Logic

When both billing methods fail, the gateway returns the most actionable error to help you resolve the issue:

​
Priority Order

  1. 403 Forbidden → Critical access issue, contact support
  2. 401 Unauthorized → Fix your provider API key
  3. 400 Bad Request → Fix your request format
  4. 500 Server Error → Provider issue or configuration problem
  5. 429 Rate Limit → Only shown if all attempts hit rate limits
Why this order? If you configured BYOK, errors from your provider keys (401, 500) are more actionable than PTB’s “insufficient credits” (429). You chose BYOK for a reason!

​
Common Error Scenarios

Error CodeWhat It MeansAction RequiredExample
401Authentication failedCheck your provider API key in settingsInvalid OpenAI API key
403Access forbiddenContact support@helicone.aiWallet suspended, model blocked
400Invalid request formatFix your request body or parametersMissing required field
429Insufficient creditsAdd credits OR configure provider keysNo Helicone credits, no BYOK
500Upstream provider errorCheck provider status or retryProvider API timeout
503Service unavailableProvider temporarily down, retry laterProvider maintenance

​
Fallback Scenarios

Setup: You have Helicone creditsResult: ✅ Request completes using Pass-Through BillingError: None - successful response
Setup: No Helicone credits, but valid provider API key configuredResult: ✅ Request completes using your provider keyError: None - successful response (PTB’s 429 is hidden since BYOK succeeded)
Setup: No Helicone credits, invalid/failing provider keyResult: ❌ Request failsError Returned: BYOK’s error (401, 500, etc.) - NOT PTB’s 429Why: You configured BYOK, so we show what’s wrong with your provider key rather than “insufficient credits”Example:
{
  "error": {
    "message": "Authentication failed",
    "type": "invalid_api_key",
    "code": 401
  }
}
Setup: No Helicone credits, no provider keys configuredResult: ❌ Request failsError Returned: 429 Insufficient creditsWhy: No alternative billing method availableExample:
{
  "error": {
    "message": "Insufficient credits",
    "type": "request_failed",
    "code": 429
  }
}
Solutions:
  1. Add Helicone credits at /credits
  2. Configure provider keys in /settings/providers
  3. Enable automatic retries with Helicone-Retry-Enabled: true to handle transient failures
Retries can help! If you’re experiencing temporary rate limits or server errors, use Helicone retry headers to automatically retry failed requests with exponential backoff.

​
Understanding Error Sources

When you see an error, you can determine which billing method it came from: PTB Errors:
  • 429: “Insufficient credits” → Add credits at /credits
  • 403: “Wallet suspended” → Contact support
BYOK Errors:
  • 401: “Invalid API key” → Check provider keys in /settings/providers
  • 500: “Provider error” → Check provider status
  • 503: “Service unavailable” → Provider having issues

​
Best Practices

Configure Both Methods

Set up both PTB and BYOK for maximum reliability. If one fails, the other serves as backup.

Monitor Credit Balance

Keep track of your Helicone credits to avoid 429 errors during critical requests.

Enable Automatic Retries

Use Helicone retry headers to automatically retry transient errors (429, 500, 503) with exponential backoff.

Log Error Details

Log the full error response to debug provider-specific issues quickly.

​
Error Handling in Code

Prefer built-in retries: Instead of implementing your own retry logic, use Helicone’s automatic retry headers by adding Helicone-Retry-Enabled: true to your requests. This handles exponential backoff automatically.

​
Retry Logic Example

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://ai-gateway.helicone.ai",
  apiKey: process.env.HELICONE_API_KEY,
});

async function callWithRetry(maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await client.chat.completions.create({
        model: "gpt-4o-mini",
        messages: [{ role: "user", content: "Hello!" }],
      });
      return response;
    } catch (error: any) {
      const status = error?.status || 500;

      // Don't retry auth errors or bad requests
      if (status === 401 || status === 403 || status === 400) {
        throw error;
      }

      // Don't retry insufficient credits unless it's the last attempt
      if (status === 429 && i === maxRetries - 1) {
        throw error;
      }

      // Retry transient errors (500, 503) with exponential backoff
      if (status >= 500 || status === 429) {
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
        continue;
      }

      throw error;
    }
  }
}

​
Error Classification

function classifyError(error: any) {
  const status = error?.status || 500;

  if (status === 401) {
    return {
      type: "authentication",
      action: "Check your API keys in settings",
      retryable: false
    };
  }

  if (status === 429) {
    return {
      type: "rate_limit",
      action: "Add credits or wait before retrying",
      retryable: true
    };
  }

  if (status >= 500) {
    return {
      type: "server_error",
      action: "Retry with exponential backoff",
      retryable: true
    };
  }

  return {
    type: "unknown",
    action: "Check error message for details",
    retryable: false
  };
}
Need Help? If you’re seeing unexpected errors or need assistance configuring fallback, contact us at support@helicone.ai or join our Discord community.
⌘I