Весело
Весело

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

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

Обновлено:

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

У POST /v1/messages ошибки — в формате Anthropic, с теми же code и текстами: пример.

Ответ 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: до трёх похожих моделей, если они есть

Все коды

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

Запрос с ошибкой не стоит денег: удержание снимается целиком. Исключение — поток, оборванный посреди ответа, см. Стриминг.

Коды 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 · Лимиты →

Вся документация одним текстом · Все модели и цены