PartyFlow

Reference: HTTP Error Codes#

Сводная таблица всех HTTP status codes, которые возвращают публичные endpoints интеграций, с диагностикой.

Некоторые коды специфичны для конкретного endpoint'а — см. колонку "Где".

Status Где Причина Ретраить?
200 Все Успех. —
400 Webhook Невалидный JSON; неизвестный формат (нет text/attachments/blocks/message.content); поле неправильного типа. Нет.
400 Bot Невалидный JSON; нет conversation_id; нет ни content ни attachments; content > 4000 символов; невалидный display_avatar_url; attachment file ещё не ready. Нет.
400 Bot Files Невалидный JSON; нет conversation_id / file_name / file_size / mime_type; неподдерживаемый MIME; фактический размер upload не совпадает с лимитами. Нет.
400 Bot Agent Runs Невалидный JSON; невалидный UUID в conversation_id / trigger_message_id / parent_message_id / {run_id}; невалидный Idempotency-Key / idempotency_key / status / sequence / content; attachments переданы не при completed. Нет.
400 Bot Execution Tasks Невалидный JSON; отсутствует conversation_id при parent_message_id; невалидный UUID в conversation_id / thread_id / parent_message_id / agent_run_id / {widget_id}; невалидный Idempotency-Key / idempotency_key / title / action / status / sequence. Нет.
400 Bot (join) Канал не найден; space mismatch; неподдерживаемый тип канала. Нет.
401 Webhook Неверный/отозванный token; подпись missing/invalid; timestamp вне окна 5 минут. Тело signature missing / signature invalid / signature timestamp outside allowed window показывается только в логах отправителя у PartyFlow — в response тело generic. Нет.
401 Bot Невалидный/отозванный token; бот is_active: false. Нет.
403 Bot Бот не состоит в канале или attachment относится к другой conversation/space. Нет — сначала POST /api/v1/bot/conversations/{id}/join.
403 Bot Execution Tasks Бот не имеет доступа к source conversation/thread, не является owning bot для task или пытается мутировать чужой widget. Нет.
404 Bot Files, Bot Agent Runs, Bot Execution Tasks Файл, run или task widget не найден для текущего bot token. Нет.
405 Все Метод не поддерживается для endpoint'а. В Bot REST есть POST, GET, PATCH и DELETE endpoints; проверяйте справочник конкретного метода. Нет.
409 Bot Agent Runs Terminal run уже нельзя менять; sequence меньше текущего или повторён с другим payload; Idempotency-Key повторно использован для другого conversation/trigger. Нет.
409 Bot Execution Tasks Terminal task уже нельзя менять; sequence устарел; Idempotency-Key повторно использован с другим payload; в thread уже есть active execution_task. Нет.
410 Webhook Webhook auto-disabled после 100 подряд ошибок. Нет — admin вручную в UI.
410 Bot Execution Tasks Runtime capability истёк или неизвестен для capability-bound endpoint'а. Нет — запросить новый task/capability или перейти на Bearer bot token endpoint.
413 Webhook Body > 256 KB. Нет — урезать payload.
429 Все Rate limit. Заголовок Retry-After: <секунд>. Да, через Retry-After.
500 Все Внутренняя ошибка. Да, с exponential backoff.
502 Webhook Внутренний сервис чата недоступен. Да, с backoff.
503 Bot (join), Bot Files, Bot Agent Runs, Bot Execution Tasks Платформа или rate limiter временно недоступны. Да, с backoff.

Почему detail ошибки не в теле#

При HTTP 401 на webhook'е тело ответа — generic error без указания, что конкретно не сошлось (подпись, timestamp, token). Это осознанное решение — не хотим облегчать подбор подписи или токена злоумышленнику.

Детали доступны только в логах инсталляции PartyFlow (на стороне отправителя смотреть нечего). Если вы admin space и отлаживаете свою интеграцию — попросите operator'а PartyFlow показать логи по этому webhook'у.

Что дальше#