SHVYDKO / API
Помилки та повтори
Розрізняйте валідацію, ліміт, нестачу резерву й недоступність моделі.
Прочитайте HTTP-статус і detail
Помилка повертається з неуспішним HTTP-статусом і полем detail. При валідації також може бути errors — список полів і повідомлень. Не очікуйте answers у такій відповіді.
{
"detail": "Request validation failed",
"errors": [
{
"field": "body.questions",
"message": "Questions must use supported types"
}
]
}Текст прикладу ілюстративний. Обробляйте статус і структуру, а не точне формулювання detail.
Статуси
| HTTP | Причина | Що зробити |
|---|---|---|
| 401 | Ключ відсутній, невідомий або відкликаний | Перевірити серверний секрет; не повторювати з тим самим ключем |
| 402 | Не вистачає доступного балансу на резерв у paid-режимі | Перевірити баланс і активні резерви |
| 403 | Організацію призупинено для перевірки білінгу | Перевірити стан організації; не обходити новими ключами |
| 409 | Резерв запиту вже завершено або прострочено | Перевірити Usage; автоматично не повторювати дію |
| 413 | JSON перевищує ліміт байтів | Скоротити контекст або розбити задачу |
| 422 | Невірна структура, ім’я моделі або відхилений контекст | Виправити запит чи зменшити контекст |
| 429 | Хвилинний ліміт або добова preview-квота | Врахувати Retry-After, якщо є; для добової квоти — 00:00 UTC |
| 502 | Модель недоступна, відповідь некоректна або сплив час | Обмежений повтор із затримкою; перевірка Usage при втраті зв’язку |
| 503 | Сервіс моделі не підключений | Перевірити стан сервісу пізніше |
Повтори мають бути обмеженими
Для хвилинного 429 використайте Retry-After та невеликий випадковий зсув між клієнтами. Добова квота preview може повернути 429 без цього заголовка: повідомлення вкаже на скидання о 00:00 UTC.
Не повторюйте 401, 402, 403, 413 або 422 без зміни причини. Для мережевих збоїв та 502 задайте невеликий ліміт спроб і загальний часовий бюджет. У POST /v1/systemone немає гарантії ідемпотентності.
Шлюз не списує кредити за запит, який він завершив помилкою моделі. Втрата відповіді на стороні вашого клієнта — інша ситуація: сервер міг уже успішно завершити роботу.