# LLM API errors explained: 429, 503 and context length

> An LLM API 429 error means you exceeded a request, token, or budget limit; inspect the error details and Retry-After header to fix it.

**An LLM API 429 error means your request was throttled because you exceeded a rate limit or a spend budget.** On thelastapi, a 429 response includes a `details.reason` field specifying whether you crossed a tokens-per-minute threshold, an account daily safety cap, or a project budget, along with a `Retry-After` header telling your code when to retry. Inspecting these machine-readable fields lets your application distinguish between temporary traffic spikes and depleted budgets without crashing.

Understanding standard error shapes like 429, 503, and context length violations makes your app reliable when upstream models stall or traffic surges.

## What causes a 429 rate limit error?

A 429 status code is not always a simple "slow down" instruction. On thelastapi, AI requests run through an OpenAI-compatible gateway at `/v1/ai/chat/completions`. When a request receives a 429, the response body provides an OpenAI-shaped error payload:

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Daily spend limit reached for this account.",
    "type": "rate_limit_error",
    "details": {
      "reason": "daily_spend",
      "limit_usd": 5,
      "spent_usd": 5.01,
      "resets_at": "2026-10-26T00:00:00.000Z",
      "raise_url": "https://thelastapi.dev/billing?edit=daily_spend_limit",
      "next_step": "Raise the account daily spend limit in Billing."
    }
  }
}
```

The `details.reason` field tells your code why the call was refused:

- `requests_per_minute`: You passed the request frequency limit. Account keys allow 300 requests per minute; project keys allow 120 requests per minute by default (settable up to 600).
- `tokens_per_minute`: Your token throughput exceeded the threshold. Account keys allow 400k tokens per minute; project keys allow 200k tokens per minute (settable up to 2M).
- `concurrency`: You have too many requests in flight at once (limit is 50 for an account key, 25 for a project key by default, settable up to 50). A call over the limit first waits up to 60 seconds for a free slot; you only see this after that wait.
- `daily_spend`: The account hit its daily safety ceiling ($5 per UTC day by default across AI and actions). Daily limits reset at midnight UTC (`limits.resets_at`).
- `project_budget`: A specific project crossed its daily AI limit ($1 per UTC day by default).
- `end_user_budget`: A specific end user identified by the `user` field or `X-Vibiz-User` header passed their configured daily ceiling.

If your 429 is caused by spend caps rather than request spikes, retrying immediately will never work until midnight UTC or until an owner raises the cap. Read more on configuring protective spending tiers in [per-user AI budgets](https://thelastapi.dev/blog/per-user-ai-budgets) and [how to handle rate limits on LLM APIs](https://thelastapi.dev/blog/handle-llm-rate-limits).

## How to handle 429 retries in code

When `details.reason` is `requests_per_minute`, `tokens_per_minute`, or `concurrency`, pause execution using the duration from the `Retry-After` header. If the error is caused by a spend cap, surface the issue or alert the project owner instead of entering a retry loop.

Here is an example using the standard OpenAI SDK configured with thelastapi credentials:

```ts
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: process.env.VIBIZ_AI_BASE_URL,
  apiKey: process.env.VIBIZ_AI_API_KEY,
});

async function callChatWithBackoff(prompt: string, attempts = 3) {
  for (let i = 0; i < attempts; i++) {
    try {
      return await openai.chat.completions.create({
        model: 'vibiz/fast',
        messages: [{ role: 'user', content: prompt }],
      });
    } catch (err: any) {
      if (err?.status === 429) {
        const reason = err?.error?.details?.reason;

        // If a budget ceiling is hit, waiting a few seconds will not help.
        if (reason === 'daily_spend' || reason === 'project_budget') {
          console.error(`Spend cap reached: ${reason}. Reset at ${err.error.details.resets_at}`);
          throw err;
        }

        // Handle short-term concurrency or rate spikes
        const retryAfterSeconds = parseInt(err?.headers?.['retry-after'] || '2', 10);
        await new Promise((resolve) => setTimeout(resolve, retryAfterSeconds * 1000));
        continue;
      }
      throw err;
    }
  }
  throw new Error('Exceeded maximum retry attempts');
}
```

If you use `@vibiz/app`, you can pass `vibiz.ai` directly to `new OpenAI(vibiz.ai)` without managing separate base URLs or keys. For a complete guide to client construction, check out [one API key for GPT, Claude and Gemini](https://thelastapi.dev/blog/one-api-key-gpt-claude-gemini) and the [@vibiz/app documentation](https://thelastapi.dev/docs/app-sdk).

## Why do 503 errors happen and what do they mean?

A 503 status code means the requested lab or model route is temporarily unavailable. 

| Error Code | HTTP Status | Meaning | Action to take |
| --- | --- | --- | --- |
| `provider_unavailable` | 503 | Upstream routes failed (`timeout`, `stall`, `circuit_open`). | Retry later with backoff. |
| `model_unavailable` | 503 | No route can run that exact model right now. | Retry after `details.retry_after_seconds` or select a different model. |
| `not_configured` | 503 | The requested model cannot be served. | Switch to an active thelastapi model tier. |

Unlike some gateways, thelastapi guarantees model fidelity: it never silently substitutes an alternative model if your selected model is down. If you ask for `anthropic/claude-opus-5.5` or `vibiz/smart` (Claude Sonnet 5.5), you get that exact model. If that lab route stalls or fails, the gateway returns a `503 model_unavailable` or `provider_unavailable` error rather than switching to an unrequested model behind your back.

When streaming responses via Server-Sent Events (SSE), an upstream failure mid-generation arrives as a final SSE event containing the error object, without the trailing `[DONE]` message:

```text
data: {"error":{"code":"provider_unavailable","message":"Provider timed out","type":"server_error"}}
```

Ensure your streaming readers check for an incoming `error` payload in incoming events before appending chunks to your user interface.

## How to solve context length exceeded errors

LLM calls fail immediately with a 400 error when prompt inputs exceed a model's window:

```json
{
  "error": {
    "code": "context_length_exceeded",
    "message": "The input is longer than the model's window.",
    "type": "invalid_request_error",
    "param": "messages"
  }
}
```

Fixing this requires trimming your payload or choosing a model with a larger context window. For example:

- `vibiz/fast` runs GPT-6 Luna ($0.10 / $0.50 per million tokens in/out).
- `vibiz/lite` runs DeepSeek V4.1 Flash ($0.14 / $0.42 per million tokens in/out) with a 1M token context window.
- `vibiz/balanced` runs Gemini 3.8 Flash ($0.825 / $4.125 per million tokens in/out) with a 1M token context window.

You can inspect the exact limits and pricing across all models via `GET /v1/ai/models` or by running `vibiz ai models --all` in your terminal. Note that certain models charge long-context rates once inputs pass specific thresholds (for instance, Claude Haiku 5.5 inputs past 100,000 tokens or GPT-6 models past 272,000 input tokens).

Additionally, watch your `max_tokens` parameter. On thelastapi, `max_tokens` defaults to 1,024 when omitted and caps at 16,384 depending on the model. Each incoming call's balance is evaluated against worst-case output token spend. If your balance cannot support the worst-case run (plus $0.50), the gateway refuses the request with `402 payment_required`.

## Managing limits and alerts across projects

To avoid surprise outages caused by rate limits and budgets, you can inspect your active consumption using the CLI:

```bash
# Check current usage across tools
vibiz usage

# Inspect usage filtered by model or API key
vibiz usage --period 7d --by model
vibiz usage --by api_key
```

Owners receive email alerts when accounts or projects reach 80% and 100% of their daily caps. A banner also appears in the web console on Overview and Usage. You can adjust limits using the CLI:

```bash
# Raise account-wide daily spend ceiling (requires full-access key)
vibiz billing limit 50

# Check or set a project's daily AI budget
vibiz ai budget 10 --project prj_123
```

Automated scripts and tools should read structured error responses to decide the right action, as detailed in our guide on [agent-friendly APIs](https://thelastapi.dev/blog/agent-friendly-api-errors). For complete documentation on keys, rate quotas, and spend ceilings, see the [AI reference](https://thelastapi.dev/docs/ai) and [Usage and limits](https://thelastapi.dev/docs/usage).

Create your account at [thelastapi.dev/start](https://thelastapi.dev/start) to build with one unified API key across all major models.

## Frequently asked questions

### What is the difference between a 429 rate limit and a 429 budget limit?

A rate limit (`requests_per_minute` or `tokens_per_minute`) means you are sending requests too quickly and should wait for the duration specified in `Retry-After`. A budget limit (`daily_spend` or `project_budget`) means you hit a daily financial cap that will not clear until midnight UTC unless an owner raises it in Billing or project settings.

### Why did my streaming LLM request stop without a [DONE] message?

If an upstream model times out or encounters an error mid-generation, the stream terminates with a final JSON error event (`data: {"error": {...}}`) instead of the standard `[DONE]` marker. Your client should parse incoming stream lines to catch errors returned mid-stream.

### How can I avoid 402 payment_required errors on large prompts?

The gateway holds an account's credits against the worst-case token cost of a call before running it. If your account balance is near zero, set an explicit, smaller `max_tokens` parameter rather than letting it default or float, or add credits via the console.

---

Published 2026-11-15 · https://thelastapi.dev/blog/llm-api-errors-429-503
