# Errors and retries

Diagnose a failure before deciding whether another request is appropriate.

## Inspect the response

Correct validation, authentication, permissions or spending-limit failures before trying again. To find the cause, read:

- the HTTP status,
- `error.metadata.type`,
- collected `issues` with field paths,
- the available `remedy_hint`.

Keep `x-request-id` for support. Never log keys, prompts or generated content. The [error catalog](https://tokenlane.de/docs/gateway/errors.md?lang=en) documents the current envelope.

## Bound retry work

For a transient connection failure, 429 or retryable server error, use bounded attempts with exponential backoff and jitter.

- Respect `Retry-After` when present.
- Check whether the SDK already retries; nested retry loops multiply requests.
- A lost response does not prove that upstream processing or charging never occurred.

For exact response recovery without another provider call or charge, opt in with one `Idempotency-Key` per logical operation and reuse it on every retry. The [idempotency guide](https://tokenlane.de/docs/guides/idempotency.md?lang=en) explains conflicts, streams and the retention limit. Requests without that header have ordinary inference behavior.

### curl

```curl
curl --request POST \
  --url 'https://api.tokenlane.de/v1/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "deepseek/deepseek-v4-flash-0731",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ],
  "max_tokens": 400
}'
```

### node

```node
import OpenAI from 'openai';

const client = new OpenAI({ baseURL: "https://api.tokenlane.de/v1", apiKey: process.env.TOKENLANE_API_KEY });
const response = await client.chat.completions.create({
  "model": "deepseek/deepseek-v4-flash-0731",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ],
  "max_tokens": 400
}, {});
console.log(response);
```

### python

```python
import os
import json
from openai import OpenAI

client = OpenAI(base_url="https://api.tokenlane.de/v1", api_key=os.environ["TOKENLANE_API_KEY"])
body = json.loads(r'''{
  "model": "deepseek/deepseek-v4-flash-0731",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ],
  "max_tokens": 400
}''')
response = client.chat.completions.create(
    model=body["model"],
    messages=body["messages"],
    max_tokens=body["max_tokens"]
)
print(response)
```

### vercel

```vercel
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';

const tokenlane = createOpenAICompatible({ name: 'tokenlane', baseURL: "https://api.tokenlane.de/v1", apiKey: process.env.TOKENLANE_API_KEY, includeUsage: true });
const result = await generateText({
  model: tokenlane("deepseek/deepseek-v4-flash-0731"),
  messages: [
  {
    "role": "user",
    "content": "Hello"
  }
],
  maxOutputTokens: 400,
});
console.log(result.text);
```

## Distinguish a failed stream

After output starts, process SSE error events as failures even when HTTP is 200. Do not silently append a second request to partial text. Surface the interruption and make any retry explicit. Gateway provider fallback is possible only before the first stream byte.
