Last updated: 2026-04-20
Error Handling & Fallback
How to handle errors and build resilient integrations with SpendLil.
SpendLil is designed so your AI never goes down because of us. Here's how errors work and how to handle them.
Response Headers
text Successful tracked response
X-SpendLil-Route: governed
X-SpendLil-Request-Id: a1b2c3d4-...Error Scenarios
| Scenario | HTTP Status | What Happens |
|---|---|---|
| Missing X-SpendLil-Key | 400 | MISSING_SPENDLIL_KEY — add the header |
| Missing or malformed provider auth | 400 | MISSING_AUTH — add Authorization: Bearer (or x-api-key / x-goog-api-key) |
| Unknown provider subdomain | 400 | UNKNOWN_PROVIDER — use a supported provider gateway |
| Invalid SpendLil key | 401 | INVALID_SPENDLIL_KEY — check your sl_ key |
| Account inactive | 403 | ACCOUNT_INACTIVE — check billing |
| Provider returns error | Provider's status | Error passed through unmodified |
| Provider unreachable | 502 | PROVIDER_ERROR — retry or fall back |
| SpendLil logging fails | Provider's status | Request succeeds, tracking gap only |
Building a Fallback
To fall back to the real provider, swap the gateway subdomain back to the provider's direct URL. Your existing auth header is already correct — no other changes needed.
javascript Fallback pattern (Node.js)
import OpenAI from 'openai';
const spendlilClient = new OpenAI({
apiKey: process.env.OPENAI_API_KEY,
baseURL: 'https://openai.gateway.spendlil.ai/v1',
defaultHeaders: { 'X-SpendLil-Key': process.env.SPENDLIL_KEY },
timeout: 30000,
});
const directClient = new OpenAI({
apiKey: process.env.OPENAI_API_KEY,
});
async function callAI(messages) {
try {
return await spendlilClient.chat.completions.create({
model: 'gpt-4o',
messages,
});
} catch (err) {
console.warn('SpendLil unavailable, calling OpenAI directly:', err.message);
return await directClient.chat.completions.create({
model: 'gpt-4o',
messages,
});
}
}