Ошибки
Формат ошибок и все коды ошибок с HTTP-статусом, значением и тем, что делать, — а также какие ошибки можно безопасно повторять.
Формат
Каждая ошибка — от API или от endpoint'ов приложения — имеет одинаковую структуру и никогда не содержит stack trace:
{
"error": {
"code": "INVALID_STATE",
"message": "Field company_size must be a number.",
"request_id": "req_7Gm2xPq9Lk4sVt1RbN8w"
}
}| Поле | Описание |
|---|---|
code | Стабильный машиночитаемый код из таблиц ниже. Ветвитесь по нему, а не по message. |
message | Понятное человеку объяснение. Оно может меняться, не разбирайте его. |
request_id | ID запроса, который также передаётся в заголовке X-Request-ID. Указывайте его, когда обращаетесь в поддержку. |
details | Необязательные дополнительные данные, зависящие от кода (см. details). |
Коды ошибок
Запрос и доступ
| Код | Статус | Значение | Что делать |
|---|---|---|---|
INVALID_REQUEST | 400 | Запрос некорректен: невалидный JSON, тело, которое не является JSON-объектом, недопустимый Idempotency-Key или query-параметр — например, limit=1000 в GET /v1/executions. | Исправьте запрос. details перечисляет проблемные поля, если они есть. |
PAYLOAD_TOO_LARGE | 413 | Тело запроса больше 128 КБ (1 МБ для POST /mcp, чьи инструменты могут передавать схему решения; 32 МБ для POST /v1/decisions/{slug} и POST /v1/hooks/{token}, чьё состояние может содержать файлы). | Отправьте тело меньшего размера — для большого состояния отправляйте только поля, нужные вопросам. См. Лимиты. |
INVALID_API_KEY | 401 | API-ключ отсутствует, имеет неверный формат, неизвестен или отозван. | Отправьте Authorization: Bearer <key> с активным ключом. |
UNAUTHORIZED | 401 | Приложение: вы не вошли, ваша сессия истекла или была завершена — через Выйти на всех устройствах или смену пароля; также неверный e-mail или пароль при входе. URL вебхуков с секретом: у вызова нет корректного Dcision-Signature или Authorization: Bearer whsec_…. | Войдите снова — или подпишите вызов вебхука текущим секретом. |
FORBIDDEN | 403 | Вам это недоступно: API-ключ используется вне /v1; рабочее пространство, участником которого вы не являетесь, — тогда details.reason равно "workspace_access"; или действие, которое не разрешает ваша роль, — наблюдатели ничего не могут менять; настройки, ключи провайдеров, секреты и участники требуют администратора; оплата, владение и удаление рабочего пространства требуют владельца. | Используйте API-ключи только на /v1. Если дело в роли, обратитесь к администратору или владельцу — в сообщении указана нужная роль. |
NOT_FOUND | 404 | Приложение: выполнение, API-ключ, шаблон, тариф, сессия оплаты, участник, приглашение, доставка или секрет не существуют в этом рабочем пространстве. URL вебхуков: токен неизвестен, был сменён или вебхук выключен. | Проверьте ID — или скопируйте URL вебхука заново на вкладке Дополнительно решения. |
CONFLICT | 409 | Изменение конфликтует с текущим состоянием: slug уже занят или заблокирован после первой публикации, черновик тем временем сохранил кто-то другой, параллельная публикация или создание, лимит (50 активных API-ключей, 50 секретов, 50 ожидающих приглашений, 10 собственных рабочих пространств), приглашение для того, кто уже в рабочем пространстве, владелец уходит без передачи владения, удаляется рабочее пространство с действующей платной подпиской, подписка уже существует или не существует. | Перезагрузите страницу, затем следуйте сообщению. |
Решения
| Код | Статус | Значение | Что делать |
|---|---|---|---|
WORKSPACE_NOT_FOUND | 404 | Режим партнёра: заголовок Dcision-Workspace или {ref} не указывает ни на одно подпространство рабочего пространства API-ключа. | Отправьте id подпространства или ext:<external_id> — см. подпространства. |
SLUG_TAKEN | 409 | Режим партнёра: перенос решения в подпространство, где уже есть решение с тем же slug. details содержит decision_id, executions, deliveries и replaceable (копия ни разу не запускалась). | При replaceable: true отправьте replace_empty: true, чтобы заменить копию. Иначе сначала переименуйте или удалите решение подпространства. |
DECISION_NOT_FOUND | 404 | В рабочем пространстве API-ключа нет решения с этим slug, или slug имеет неверный формат. | Проверьте slug и то, что ключ принадлежит рабочему пространству решения. |
DECISION_NOT_DEPLOYED | 409 | Решение существует, но ни разу не публиковалось. | Опубликуйте его на вкладке Публикация. |
DECISION_DISABLED | 409 | Endpoint решения отключён. | Нажмите Включить endpoint на его вкладке Публикация. |
INVALID_STATE | 422 | Состояние не соответствует схеме состояния решения или слишком велико — само по себе или вместе с вопросами для бюджета токенов движка. message называет поле или лимит. | Исправьте состояние; для бюджета токенов отправляйте только поля, нужные вопросам. Не повторяйте его без изменений. |
INVALID_SCHEMA | 422 | Схема решения недействительна — при сохранении или публикации черновика. details перечисляет все проблемы. | Исправьте проблемы в редакторе (К ошибке). |
IDEMPOTENCY_CONFLICT | 409 | Idempotency-Key уже использовался за последние 24 часа с другим запросом — или, с Retry-After: 1, первый запрос с этим ключом ещё выполняется. | С Retry-After: подождите и повторите с тем же ключом, чтобы получить сохранённый ответ. Без него: используйте новый ключ для нового запроса — см. Идемпотентность. |
Лимиты и оплата
| Код | Статус | Значение | Что делать |
|---|---|---|---|
RATE_LIMITED | 429 | Слишком много запросов вашего рабочего пространства в текущую минуту — или собственные лимиты Playground, или, в приложении, слишком много действий с оплатой (оформление, смена тарифа, портал…), приглашений, кодов входа или попыток входа. | Подождите Retry-After секунд, затем повторите — см. Rate limits. |
CREDITS_EXHAUSTED | 402 | Включённые в тариф решения за период израсходованы, а у рабочего пространства не осталось кредитов. | Владелец докупает кредиты или включает автопополнение на странице Оплата (details.billingUrl) либо повышает тариф. Повторы до этого не помогут. |
SPEND_CAP_REACHED | 402 | Достигнут лимит расходов рабочего пространства за платёжный цикл. | Владелец повышает или убирает лимит на странице Оплата, либо дождитесь details.periodEnd. |
QUOTA_EXCEEDED | 402 | Тариф, настроенный с жёстким лимитом — или без цены за 1 млн решений, — израсходовал все включённые решения за период, поэтому не может продолжать за счёт кредитов. | Повысьте тариф или дождитесь details.periodEnd. Повторы раньше не помогут. |
PLAN_LIMIT_REACHED | 402 | В рабочем пространстве уже максимальное число решений для его тарифа. | Удалите решение или повысьте тариф. |
PAYMENT_FAILED | 402 | Карта была отклонена при смене тарифа. | Обновите способ оплаты и попробуйте снова. |
BILLING_NOT_CONFIGURED | 503 | Этот тариф, период или валюту пока нельзя купить онлайн. | Попробуйте позже или напишите на sales@dcision.io. |
BILLING_PROVIDER_ERROR | 502 | Платёжный провайдер не смог обработать запрос. | Попробуйте снова чуть позже. |
Движок
Прежде чем вернуть одну из этих ошибок, Dcision уже повторяет временные сбои движка — до 2 повторов в пределах timeoutMs решения. Решение с onEngineError: "fallback" вместо этого отвечает 200 со своим действием fallback — для всех кодов ниже, кроме ENGINE_NOT_CONFIGURED, — см. Настройки решения.
| Код | Статус | Значение | Что делать |
|---|---|---|---|
ENGINE_NOT_CONFIGURED | 424 | У рабочего пространства нет пригодных учётных данных движка: выбран Мой ключ провайдера, но для этого провайдера не сохранён ключ, или ключ движка Dcision недоступен. | Добавьте ключ в Настройки → Движок или переключитесь на ключ Dcision. |
ENGINE_TIMEOUT | 504 | Движок не ответил в пределах timeoutMs решения. | Повторите с backoff и тем же Idempotency-Key; если это случается часто, увеличьте timeoutMs. |
ENGINE_RATE_LIMITED | 503 | Провайдер движка перегружен или упёрся в rate limit, либо у общего ключа движка Dcision не нашлось свободного слота до дедлайна. | Повторите с backoff. Со своим ключом проверьте лимиты провайдера. |
ENGINE_UNAVAILABLE | 503 | Провайдер движка дал сбой или недоступен. | Повторите с backoff. |
ENGINE_INVALID_REQUEST | 502 | Провайдер отклонил запрос; сообщение содержит его причину. | Обычно это не временная ошибка: проверьте состояние и модель, затем обратитесь в поддержку с ID запроса. |
ENGINE_AUTH_FAILED | 502 | Провайдер отклонил ключ движка. | Исправьте или замените ключ провайдера в Настройки → Движок. |
ENGINE_ERROR | 502 | Движок ответил вне контракта решения (ответ отсутствует или неизвестен). | Повторите один раз; если ошибка сохраняется, обратитесь в поддержку с ID запроса. |
Сервер
| Код | Статус | Значение | Что делать |
|---|---|---|---|
INTERNAL_ERROR | 500 | Непредвиденная ошибка на стороне Dcision. | Повторите с backoff; если ошибка сохраняется, обратитесь в поддержку с ID запроса. |
Повторные попытки
| Повторять | Не повторять без изменений |
|---|---|
429 RATE_LIMITED — после Retry-After | 400, 401, 403, 404, 413, 422 |
409 IDEMPOTENCY_CONFLICT с Retry-After — с тем же ключом, после ожидания | Любой другой 409 |
500 INTERNAL_ERROR | 402 CREDITS_EXHAUSTED, SPEND_CAP_REACHED, QUOTA_EXCEEDED, PLAN_LIMIT_REACHED, PAYMENT_FAILED |
503 ENGINE_RATE_LIMITED, ENGINE_UNAVAILABLE | 424 ENGINE_NOT_CONFIGURED |
504 ENGINE_TIMEOUT | 502 ENGINE_AUTH_FAILED, ENGINE_INVALID_REQUEST |
502 ENGINE_ERROR — один раз | |
| Сетевые ошибки и таймауты на вашей стороне |
Отправляйте Idempotency-Key, чтобы повтор после потерянного ответа не запустил — и не тарифицировал — решение дважды. Полный клиент приведён в Идемпотентных повторах.
Ошибки никогда не тарифицируются, как и fallback из-за ошибок движка. Недопустимые состояния и сбои движка записываются как выполнения со статусом Ошибка, чтобы их можно было изучить — в приложении или через GET /v1/executions?status=error.
Подробности
Для некоторых кодов details содержит структурированные данные:
{
"error": {
"code": "INVALID_SCHEMA",
"message": "The decision schema is invalid.",
"request_id": "req_7Gm2xPq9Lk4sVt1RbN8w",
"details": [{ "path": "questions.0.options", "message": "Add at least 2 options (besides \"other\")." }]
}
}{
"error": {
"code": "CREDITS_EXHAUSTED",
"message": "The 2.5M decisions included in the Developer plan are used up and the workspace has no credits left. Add credits or turn on automatic recharge.",
"request_id": "req_Lz4Wq8nT1vXc7Rm2Kp9H",
"details": {
"used": 2500000,
"included": 2500000,
"availableCents": 0,
"currency": "usd",
"billingUrl": "https://app.dcision.io/billing"
}
}
}{
"error": {
"code": "SPEND_CAP_REACHED",
"message": "The workspace reached its spend cap of $50.00 for this billing cycle. Raise the cap or wait until 2026-11-01.",
"request_id": "req_Qm8Vr2Lx5Nc1Tw7Hk4Jd",
"details": {
"spendCapCents": 5000,
"spentCents": 5000,
"currency": "usd",
"periodEnd": "2026-11-01T00:00:00.000Z",
"billingUrl": "https://app.dcision.io/billing"
}
}
}{
"error": {
"code": "FORBIDDEN",
"message": "You don't have access to this workspace.",
"request_id": "req_Pw3Nx8Kd1Lq6Tz2Vb9Rc",
"details": { "reason": "workspace_access" }
}
}| Код | details |
|---|---|
INVALID_REQUEST | [{ "path", "message" }] для недопустимых полей, если доступно |
INVALID_SCHEMA | [{ "path", "message" }] — каждая проблема схемы |
CREDITS_EXHAUSTED | used, included, availableCents (остаток кредита в центах currency — ноль или немного меньше нуля), currency (usd или brl), billingUrl |
SPEND_CAP_REACHED | spendCapCents, spentCents (расходы цикла за счёт кредитов, в центах), currency, periodEnd (ISO 8601), billingUrl |
QUOTA_EXCEEDED | used, included, periodEnd (ISO 8601), upgradeUrl |
PLAN_LIMIT_REACHED | limit, used, upgradeUrl |
FORBIDDEN (доступ к рабочему пространству) | { "reason": "workspace_access" } — вы не являетесь (больше не являетесь) участником этого рабочего пространства. Отказы по роли не содержат details. |
CONFLICT (устаревший черновик) | currentRevision |
PAYMENT_FAILED | code, declineCode от платёжной сети карты |
События вебхуков
Событие decision.completed из документа OpenAPI — запрос, отправляемый назначениям-вебхукам, его заголовки, каждое поле события и ответы, которых ожидает Dcision.
Rate limits
Лимиты запросов на рабочее пространство для каждого тарифа, отдельные окна для решений и чтения, заголовки X-RateLimit в каждом вызове, Retry-After при 429 и как снижать нагрузку.