Ошибки и лимиты
Коды ошибок PlusVibe API: 401 (ключ), 402 (баланс), 403 (IP), 429 (лимит частоты). Как обрабатывать ошибки и повторять запросы с экспоненциальной задержкой.
Ошибки, сформированные PlusVibe на /v1/*, имеют JSON-envelope error.message, error.type и error.code. Не используйте текст сообщения или заголовки стороннего сервиса как контракт.
Формат ошибки
{
"error": {
"message": "insufficient balance",
"type": "insufficient_quota",
"code": 402
}
}Коды ответов
| Параметр | Тип | Описание |
|---|---|---|
401 | authentication_error / 401 | Нет, формат неверен или ключ отключён. Не повторять до исправления credentials. |
402 | insufficient_quota / 402 | Нет доступного баланса или лимита. Исправьте причину; только исчерпанное окно подписки может вернуть Retry-After: 1. |
403 | permission_error или policy type / 403 | IP, модель или политика не разрешают запрос. Не повторять без изменения запроса или настроек. |
429 | rate_limit_exceeded или inflight_client_cap / 429 | Лимит частоты либо одновременных запросов. Повторять только после Retry-After. |
410 | media_endpoint_retired / media_endpoint_retired | Только для retired media routes. Не повторять; перейдите на /api/media/generate. |
413 | invalid_request_error / 413 | Только Files API: файл больше 50 MiB. Уменьшите файл, затем создайте новый запрос. |
503 | overloaded / 503 | Глобальная перегрузка edge. Повторять после Retry-After: 2. Другие 503 могут быть не retryable без изменения модели или запроса. |
Заголовки ответа
| Параметр | Тип | Описание |
|---|---|---|
x-pv-cost-rub | string | Best-effort оценка списания в рублях с 4 знаками в успешном non-streaming text-ответе. Не является обязательным заголовком. |
x-pv-generation-id | string | ID записи в истории использования (GET /v1/generations/{id}). Возвращается только для не-потоковых (non-streaming) запросов chat/completions. |
Retry-After | integer | Секунды ожидания. Edge ставит его на 429 частоты, 429 concurrency (5), 503 global overload (2) и некоторых временных 402. Не предполагается для каждого 429/503. |
Для потоковых запросов (
stream: true) x-pv-generation-id не возвращается, так как биллинг завершается после окончания стрима. Историю запросов смотрите через GET /v1/generations.Лимиты частоты и параллелизм
| Параметр | Тип | Описание |
|---|---|---|
0 / 100 / 1 000 / 10 000 ₽ | RPM | 80 / 200 / 350 / 650 запросов в минуту соответственно. Публикуется только исполняемый RPM: TPM не ограничивается как клиентский runtime-лимит. |
RPM account-wide | edge | RPM считается по клиентскому аккаунту сразу для всех его API-ключей. Индивидуальный лимит клиента может только уменьшить tier RPM. |
Edge concurrency | default | По умолчанию не более 16 одновременных запросов на аккаунт: 429 и Retry-After: 5. Общий защитный предел - 60 одновременных запросов: 503 и Retry-After: 2. Эти значения могут быть настроены сервисом. |
Повтор запросов (retry)
Для retryable ответа сначала используйте Retry-After, если он есть. Без заголовка не считайте любой 429 или 503 автоматически retryable: проверьте HTTP status и публичный error.type, устраните не-retryable причину и используйте ограниченный backoff только для временной ошибки.
import time, requests
def call_with_retry(url, headers, payload, max_retries=5):
for attempt in range(max_retries):
r = requests.post(url, headers=headers, json=payload)
if r.status_code == 429:
# уважаем Retry-After, иначе экспоненциальная задержка
wait = int(r.headers.get("Retry-After", 2 ** attempt))
time.sleep(wait)
continue
return r
return r