Ошибки и повторы
Коды ошибок 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: до трёх похожих моделей, если они есть |
Все коды
| 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. |
Запрос с ошибкой не стоит денег: удержание снимается целиком. Исключение — поток, оборванный посреди ответа, см. Стриминг.
Коды 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: повтори с паузой.