Error Handling & Fallback

Planck 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 Planck 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 BYOK first. If your provider key cannot serve the request, the gateway can fall back to PTB when credits and a managed provider route are available.

Error Priority Logic

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

Priority Order

403 Forbidden → Critical access issue, contact support
401 Unauthorized → Fix your provider API key
400 Bad Request → Fix your request format
500 Server Error → Provider issue or configuration problem
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 Code	What It Means	Action Required	Example
401	Authentication failed	Check your provider API key in settings	Invalid OpenAI API key
403	Access forbidden	Contact support@inquantum.ai	Wallet suspended, model blocked
400	Invalid request format	Fix your request body or parameters	Missing required field
429	Insufficient credits	Add credits OR configure provider keys	No Planck credits, no BYOK
500	Upstream provider error	Check provider status or retry	Provider API timeout
503	Service unavailable	Provider temporarily down, retry later	Provider maintenance

Fallback Scenarios

Scenario 1: BYOK Succeeds

Setup: You have a valid provider key configured or providedResult: ✅ Request completes using Bring Your Own KeysError: None - successful response

Scenario 2: BYOK Fails, PTB Succeeds

Setup: Your provider key fails, but you have Planck credits and a managed route is availableResult: ✅ Request completes using Pass-Through BillingError: None - successful response

Scenario 3: BYOK Fails, PTB Fails

Setup: Your provider key fails and PTB is unavailable or also failsResult: ❌ Request failsError Returned: The most actionable error from the failed attemptsWhy: If your provider key is invalid, that error is usually more actionable than a generic fallback failure.Example:

{
  "error": {
    "message": "Authentication failed",
    "type": "invalid_api_key",
    "code": 401
  }
}

Scenario 4: No BYOK Configured, PTB Fails

Setup: No Planck credits and 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:

Add Planck credits
Configure provider keys
Enable automatic retries with Planck-Retry-Enabled: true to handle transient failures

Retries can help! If you’re experiencing temporary rate limits or server errors, use Planck 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
403: “Wallet suspended” → Contact support

BYOK Errors:

401: “Invalid API key” → Check provider keys
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 Planck credits to avoid 429 errors during critical requests.

Enable Automatic Retries

Use Planck 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 Planck’s automatic retry headers by adding Planck-Retry-Enabled: true to your requests. This handles exponential backoff automatically.

Retry Logic Example

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.inquantum.ai",
  apiKey: process.env.PLANCK_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
  };
}

Automatic Retries - Configure retry headers for handling transient failures
Provider Routing - Learn how to configure fallback providers
Settings: Provider Keys - Add your provider API keys
Credits - Add Planck credits for Pass-Through Billing

Need Help? If you’re seeing unexpected errors or need assistance configuring fallback, contact us at support@inquantum.ai.

Getting Started

AI Gateway

Observability & Analytics

Prompt Management

Async Logging

Custom Logs

Error Handling & Fallback

How Fallback Works

Pass-Through Billing (PTB)

Bring Your Own Keys (BYOK)

Error Priority Logic

Priority Order

Common Error Scenarios

Fallback Scenarios

Understanding Error Sources

Best Practices

Configure Both Methods

Monitor Credit Balance

Enable Automatic Retries

Log Error Details

Error Handling in Code

Retry Logic Example

Error Classification

​How Fallback Works

Pass-Through Billing (PTB)

Bring Your Own Keys (BYOK)

​Error Priority Logic

​Priority Order

​Common Error Scenarios

​Fallback Scenarios

​Understanding Error Sources

​Best Practices

Configure Both Methods

Monitor Credit Balance

Enable Automatic Retries

Log Error Details

​Error Handling in Code

​Retry Logic Example

​Error Classification

​Related Resources

How Fallback Works

Error Priority Logic

Priority Order

Common Error Scenarios

Fallback Scenarios

Understanding Error Sources

Best Practices

Error Handling in Code

Retry Logic Example

Error Classification

Related Resources