---
title: "Ошибки и повторы"
description: "Коды ошибок API: что значит каждый и что делать, какие запросы повторять, экспоненциальная пауза и Retry-After. Ошибка не стоит денег."
url: https://veselo.ai/docs/errors
updated: 2026-11-14T20:55:06.831Z
---

# Ошибки и повторы

Коды ошибок API: что значит каждый и что делать, какие запросы повторять, экспоненциальная пауза и Retry-After. Ошибка не стоит денег.

Обновлено: 14 ноября 2026 г.

Ошибки приходят в формате OpenAI, поэтому SDK OpenAI понимают их без доработок. Текст — по-русски, `code` — постоянный английский идентификатор: в коде проверяй его, а не текст.

У `POST /v1/messages` ошибки — в формате Anthropic, с теми же `code` и текстами: [пример](https://veselo.ai/docs/anthropic#errors).

**Ответ 402**

```
{
  "error": {
    "message": "Не хватает денег на балансе для этого запроса.",
    "type": "billing_error",
    "code": "insufficient_balance",
    "param": null,
    "request_id": "req_5b2e9c0d41f84a7f9e3c2a1b0d6f8e47",
    "required_rub": 1.97,
    "available_rub": 0.4,
    "topup_url": "https://veselo.ai/developer/wallet"
  }
}
```

| Поле | Что это |
| --- | --- |
| `message` | что случилось, по-русски |
| `type` | класс ошибки в духе OpenAI: `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `billing_error`, `api_error` |
| `code` | точная причина — из таблицы ниже |
| `param` | поле запроса, которое не прошло проверку, или `null` |
| `request_id` | номер запроса — назови его поддержке; он же в заголовке `x-request-id` |
| `required_rub`, `available_rub`, `topup_url` | у `insufficient_balance`: сколько нужно на удержание, сколько доступно и где пополнить |
| `limit_rub`, `spent_rub` | у `key_limit_reached`: месячный лимит ключа и сколько он потратил в этом месяце |
| `alternatives` | у `model_unavailable`: до трёх похожих моделей, если они есть |

## Все коды

| HTTP | code | Что случилось | Что делать |
| --- | --- | --- | --- |
| 400 | `invalid_request` | Неверный запрос: проверь поле, указанное в param. | Сверь тело запроса с документацией метода. В param — имя поля, которое не прошло проверку. |
| 401 | `missing_api_key` | Нет ключа API. Выпусти его на veselo.ai/developer («Новый ключ») и передай в заголовке Authorization: Bearer sk-vsl-… | Выпусти ключ в кабинете veselo.ai/developer и передай его в заголовке Authorization. |
| 401 | `invalid_api_key` | Ключ не найден или отозван. | Проверь, что ключ скопирован целиком. Отозванный ключ не оживает — выпусти новый в кабинете. |
| 402 | `insufficient_balance` | Не хватает денег на балансе для этого запроса. | Пополни API-счёт в кабинете: veselo.ai/developer/wallet (баланс для роликов запросы по API не оплачивает). Или уменьши max_tokens: под запрос удерживается его наибольшая цена. |
| 403 | `key_limit_reached` | Запрос не помещается в месячный лимит ключа. | Под запрос удерживается его наибольшая цена: уменьши max_tokens, подними лимит ключа в кабинете или подожди начала месяца. |
| 403 | `model_not_allowed` | Эта модель у нас недоступна. | Выбери другую модель из GET /v1/models. |
| 403 | `account_blocked` | Аккаунт заблокирован. | Напиши в поддержку veselo.ai. |
| 404 | `model_not_found` | Модель с таким id не найдена. | Возьми id из GET /v1/models — он вида vendor/model, ровно как в поле id списка. |
| 404 | `not_found` | Такого адреса в API нет. | Проверь метод и путь: базовый адрес — https://veselo.ai/v1. |
| 404 | `job_not_found` | Задача не найдена. | Проверь id задачи: задачи видны только ключам того же аккаунта. |
| 409 | `idempotency_conflict` | Этот Idempotency-Key уже использован с другим телом запроса. | Для нового запроса возьми новый Idempotency-Key; для повтора — то же тело. |
| 413 | `payload_too_large` | Запрос слишком большой. | Тело — до 25 МБ. Большие файлы передавай ссылкой. |
| 422 | `content_refused` | Запрос отклонён проверкой содержания. | Перепиши запрос: нейросеть не принимает такое содержание. Деньги не списаны. |
| 429 | `rate_limited` | Слишком много запросов. | Подожди столько секунд, сколько в заголовке Retry-After, и повтори. |
| 500 | `internal_error` | Что-то сломалось у нас. | Повтори через минуту. Не помогло — напиши в поддержку и приложи request_id. |
| 502 | `upstream_error` | Нейросеть ответила ошибкой. | Повтори запрос или выбери другую модель. Деньги не списаны. |
| 503 | `model_unavailable` | Модель сейчас недоступна. | Повтори позже или возьми модель из поля alternatives. |
| 503 | `api_disabled` | API временно выключено. | Повтори позже: API включится снова. Деньги не списаны. |
| 504 | `upstream_timeout` | Нейросеть не ответила вовремя. | Повтори запрос; для длинных ответов включи stream: true. |

> Запрос с ошибкой не стоит денег: удержание снимается целиком. Исключение — поток, оборванный посреди ответа, см. [Стриминг](https://veselo.ai/docs/streaming#abort).

Коды `job_not_found` и `idempotency_conflict` зарезервированы: сейчас их не возвращает ни один метод.

## Что повторять

| Ответ | Повторять | Как |
| --- | --- | --- |
| 429 `rate_limited` | да | через столько секунд, сколько в заголовке `Retry-After` |
| 500 `internal_error`, 502 `upstream_error` | да | с паузой; не помогло за 3–5 попыток — напиши в поддержку и приложи `request_id` |
| 503 `model_unavailable` | да | с паузой — или сразу возьми модель из `alternatives`, у неё своя цена |
| 503 `api_disabled` | позже | API выключено на время: повторяй раз в несколько минут |
| 504 `upstream_timeout` | да | лучше со `stream: true` или меньшим `max_tokens` |
| обрыв соединения | да | с паузой; помни, что запрос без стриминга мог дойти и будет оплачен |
| 402 `insufficient_balance` | нет | пополни баланс или уменьши `max_tokens`, потом повтори |
| 400, 401, 403, 404, 413, 422 | нет | исправь запрос, ключ, модель или текст |

## Пауза между попытками

- Есть заголовок `Retry-After` — жди столько секунд.
- Нет — экспоненциальная пауза: 1, 2, 4, 8, 16 секунд плюс случайная добавка до секунды, чтобы параллельные запросы не повторялись разом.
- Не больше 5 попыток, потом — ошибка наверх.
- SDK OpenAI уже повторяют 429, 5xx и обрывы связи: по умолчанию 2 раза, с учётом `Retry-After`. Число повторов — `max_retries` в Python и `maxRetries` в JavaScript.

## Примеры

**Python**

```
import os
import openai
from openai import OpenAI

client = OpenAI(
    base_url="https://veselo.ai/v1",
    api_key=os.environ["VESELO_API_KEY"],
    max_retries=4,  # 429, 5xx и обрывы связи SDK повторит сам, с паузой и учётом Retry-After
)

try:
    r = client.chat.completions.create(
        model="deepseek/deepseek-v4.1-flash-ultrafast",
        messages=[{"role": "user", "content": "Объясни в двух предложениях, что такое API."}],
        max_tokens=300,
    )
    print(r.choices[0].message.content, f"({r.usage.cost_rub} ₽)")
except openai.APIStatusError as e:
    err = e.body if isinstance(e.body, dict) else {}
    code = err.get("code")
    if code == "insufficient_balance":
        print(f"Не хватает денег: нужно {err['required_rub']} ₽, доступно {err['available_rub']} ₽. Пополнить: {err['topup_url']}")
    elif code == "key_limit_reached":
        print(f"Запрос не помещается в месячный лимит ключа: {err['limit_rub']} ₽")
    elif code == "model_unavailable":
        print("Модель недоступна, можно взять:", err.get("alternatives"))
    else:
        print(f"Ошибка {e.status_code} {code}: {err.get('message')} (request_id {err.get('request_id')})")
except openai.APIConnectionError:
    print("Нет связи с API — повтори позже")
```

**JavaScript без SDK**

```
const RETRY = new Set([429, 500, 502, 503, 504]);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const backoff = (i) => Math.min(2 ** i, 30) * 1000 + Math.random() * 1000; // 1, 2, 4, 8… с

async function chat(body, attempts = 5) {
  for (let i = 0; ; i++) {
    let res;
    try {
      res = await fetch('https://veselo.ai/v1/chat/completions', {
        method: 'POST',
        headers: { Authorization: `Bearer ${process.env.VESELO_API_KEY}`, 'Content-Type': 'application/json' },
        body: JSON.stringify(body),
      });
    } catch (e) {
      if (i + 1 >= attempts) throw e; // нет связи
      await sleep(backoff(i));
      continue;
    }
    if (res.ok) return res.json();
    // ответ прокси может быть не JSON — тогда только код HTTP
    const { error } = await res.json().catch(() => ({ error: { code: `http_${res.status}`, message: res.statusText } }));
    if (!RETRY.has(res.status) || i + 1 >= attempts) {
      throw Object.assign(new Error(`${res.status} ${error.code}: ${error.message}`), { status: res.status, error });
    }
    const after = Number(res.headers.get('retry-after'));
    await sleep(after > 0 ? after * 1000 : backoff(i));
  }
}

try {
  const r = await chat({
    model: 'deepseek/deepseek-v4.1-flash-ultrafast',
    max_tokens: 300,
    messages: [{ role: 'user', content: 'Объясни в двух предложениях, что такое API.' }],
  });
  console.log(r.choices[0].message.content, `(${r.usage.cost_rub} ₽)`);
} catch (e) {
  if (e.error?.code === 'insufficient_balance') console.log('Пополни баланс:', e.error.topup_url);
  else console.log(e.message, e.error?.request_id ?? '');
}
```

## Если ответ — не JSON

Если наш сервер недоступен, ответ может прийти от прокси — страницей HTML с кодом 502 или 504. Обрабатывай его как 502: повтори с паузой.

[← Методы API](https://veselo.ai/docs/reference) · [Лимиты →](https://veselo.ai/docs/limits)

[Вся документация одним текстом](https://veselo.ai/docs/llms.txt) · [Все модели и цены](https://veselo.ai/models)

## Разделы документации

### Начало

- [Быстрый старт](https://veselo.ai/docs)
- [Ключи](https://veselo.ai/docs/auth)
- [Цены и списания](https://veselo.ai/docs/pricing)
- [Модели](https://veselo.ai/docs/models)

### Как сделать

- [Сообщения и параметры](https://veselo.ai/docs/chat)
- [Стриминг](https://veselo.ai/docs/streaming)
- [Вызов функций](https://veselo.ai/docs/tools)
- [Ответ в JSON](https://veselo.ai/docs/structured-output)
- [Провайдеры](https://veselo.ai/docs/providers)
- [Без цензуры](https://veselo.ai/docs/uncensored)
- [Картинки во входе](https://veselo.ai/docs/vision)
- [Картинки](https://veselo.ai/docs/images)
- [Видео](https://veselo.ai/docs/video)
- [Озвучка](https://veselo.ai/docs/speech)
- [Музыка](https://veselo.ai/docs/music)
- [SDK и программы](https://veselo.ai/docs/sdks)
- [Claude Code](https://veselo.ai/docs/anthropic)
- [Ключ для нейросети](https://veselo.ai/docs/agents)
- [MCP](https://veselo.ai/docs/mcp)

### Справочник

- [Методы API](https://veselo.ai/docs/reference)
- **Ошибки**
- [Лимиты](https://veselo.ai/docs/limits)
- [Заголовки](https://veselo.ai/docs/headers)

### Ещё

- [Вопросы](https://veselo.ai/docs/faq)
- [Данные и приватность](https://veselo.ai/docs/privacy)
- [Изменения](https://veselo.ai/docs/changelog)
