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.

Error Response Format

When the gateway can return a normal HTTP response, errors use a shared JSON envelope:

Error response

{
  "success": false,
  "error": {
    "message": "Model not found: example-model",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

Branch on the HTTP status and stable error.code. Display error.message to developers, but do not build application logic by matching message text. When debugging, log the complete response and the X-Request-ID or Planck-Id response header.

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” (402). You chose BYOK for a reason!

Common Error Responses

Status	Typical meaning	Retry automatically?
`400`	Invalid fields, unsupported parameters, context length, or content rejection	No; change the request.
`401`	Missing or invalid Planck or provider credential	No; fix credentials.
`402`	Insufficient Planck credits	No; add credits or use BYOK.
`403`	Policy, safety, geography, model access, or suspended wallet	No; resolve the restriction.
`404`	Model, file, or asynchronous job was not found	No; verify the identifier.
`408` / `504`	Request or provider timeout	Yes, if the operation is safe to repeat.
`413`	Uploaded body or file is too large	No; reduce the payload.
`429`	Organization, provider, or quota rate limit	Yes; honor `Retry-After`.
`502` / `503`	Provider or gateway dependency failure	Usually, with exponential backoff.

{
  "success": false,
  "error": {
    "message": "The request contains an unsupported parameter",
    "type": "invalid_request",
    "code": "unsupported_parameter",
    "param": "response_format"
  }
}

{
  "success": false,
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

{
  "success": false,
  "error": {
    "message": "Insufficient balance. Available: $0.00, needed: $0.01",
    "type": "insufficient_balance",
    "code": "insufficient_credits"
  }
}

{
  "success": false,
  "error": {
    "message": "Rate limit exceeded: production (100 requests per 60 seconds)",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

{
  "success": false,
  "error": {
    "message": "The selected provider is temporarily unavailable",
    "type": "unavailable",
    "code": "provider_unavailable"
  }
}

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: 402 Insufficient creditsWhy: No alternative billing method availableExample:

{
  "error": {
    "message": "Insufficient credits",
    "type": "insufficient_balance",
    "code": "insufficient_credits"
  }
}

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:

402: “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 402 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.

Errors During a Stream

Before streaming begins, failures return a non-2xx HTTP response using the JSON envelope above. After SSE headers are committed, the HTTP status can remain 200; Chat Completions sends an error object in a data: frame and then terminates the stream:

Chat Completions stream error

data: {"error":{"message":"Provider stream timed out","type":"timeout","code":"stream_timeout","status":504,"retryable":true}}

data: [DONE]

Native Anthropic streaming instead uses a named error event. See Native Anthropic streaming. If partial output is already visible, retry only if your UI first removes or replaces that output. Otherwise, users can receive duplicated text.

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/v1",
  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;
      }

      // Credits and credentials require a configuration change
      if (status === 402) {
        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: "Wait before retrying and honor Retry-After",
      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.

Get Started

Models & Inference

Reliability & Controls

Observability

Prompt Management

Integrations

Error Handling & Fallback

Error Response Format

How Fallback Works

Pass-Through Billing (PTB)

Bring Your Own Keys (BYOK)

Error Priority Logic

Priority Order

Common Error Responses

Fallback Scenarios

Understanding Error Sources

Best Practices

Configure Both Methods

Monitor Credit Balance

Enable Automatic Retries

Log Error Details

Errors During a Stream

Error Handling in Code

Retry Logic Example

Error Classification

​Error Response Format

​How Fallback Works

Pass-Through Billing (PTB)

Bring Your Own Keys (BYOK)

​Error Priority Logic

​Priority Order

​Common Error Responses

​Fallback Scenarios

​Understanding Error Sources

​Best Practices

Configure Both Methods

Monitor Credit Balance

Enable Automatic Retries

Log Error Details

​Errors During a Stream

​Error Handling in Code

​Retry Logic Example

​Error Classification

​Related Resources

Error Response Format

How Fallback Works

Error Priority Logic

Priority Order

Common Error Responses

Fallback Scenarios

Understanding Error Sources

Best Practices

Errors During a Stream

Error Handling in Code

Retry Logic Example

Error Classification

Related Resources