Отказы
Все отказы одной формы. Решение принимайте по code; message написан по-русски для человека, который будет читать ваш журнал, и может меняться.
{ "ok": false, "error": {
"code": "quota_exceeded",
"message": "Монеты на этот период кончились (израсходовано 1000 из 1000)…",
"details": { "reason": "out_of_coins" } } }details есть не у всех отказов.
| Код | HTTP | Что случилось | Что делать |
|---|---|---|---|
unauthorized | 401 | Нет ключа, ключ неверен или отозван | Не повторять. Проверить ключ у мебельной компании |
forbidden | 403 | Рабочее место в /handoff не принадлежит этой учётной записи | Не повторять. Уточнить название места |
not_found | 404 | Нет такого разговора, хода или ссылки; либо в разговоре ещё ничего не собрано | Не повторять вслепую |
invalid_request | 400 | Тело не по договору: пустой text, битый b64, больше двух картинок | Не повторять. Чинить запрос |
conflict_busy | 409 | По разговору уже идёт ход; либо ход, который просят остановить, уже кончился | Дождаться вебхука. Повторять просьбу не надо |
quota_exceeded | 402 | Кончились монеты или подписка | Не повторять. Сообщить мебельной компании |
payload_too_large | 413 | Картинка больше 5 МБ | Пережать картинку |
rate_limited | 429 | Слишком много ходов идёт разом | Повторить через минуту |
png_unsupported | 501 | Запрошен format=png | Взять svg и сконвертировать у себя |
internal | 500 | Беда на нашей стороне | Повторить один раз через минуту; не прошло — написать нам |
Повторять или нет
Повторять имеет смысл только rate_limited, internal и сетевые обрывы. Всё остальное повтором не лечится: 401 не станет 200 от третьей попытки, а 409 означает, что работа уже идёт.
Повторяя POST /turns после обрыва сети, обязательно шлите тот же Idempotency-Key: иначе вы купите второй ход за те же деньги.
Подробности у quota_exceeded
"details": { "reason": "out_of_coins" }reason | Что это значит |
|---|---|
out_of_coins | Монеты периода кончились; можно добрать пакетом |
period_over | Период кончился, подписка не продлена |
canceled | Подписка отменена |
no_subscription | У учётной записи нет подписки вовсе |
Всё это чинится в кабинете мебельной компании, а не вами: вы можете только показать, что работа встала, и кому об этом сказать.
Отказ — не то же, что неудачный ход
Отказ приходит синхронно, кодом HTTP, и означает, что ход не начался. Неудачный ход приходит вебхуком со status: "failed" и означает, что работа шла, но не сошлась. Деньги в первом случае не тратятся вовсе, во втором — тоже не тратятся, но время потрачено.
Эта страница разметкой: /docs/api/errors.md · вся документация одним файлом: /llms-full.txt