Ошибки

Формат ошибок и все коды ошибок с 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_idID запроса, который также передаётся в заголовке X-Request-ID. Указывайте его, когда обращаетесь в поддержку.
detailsНеобязательные дополнительные данные, зависящие от кода (см. details).

Коды ошибок

Запрос и доступ

КодСтатусЗначениеЧто делать
INVALID_REQUEST400Запрос некорректен: невалидный JSON, тело, которое не является JSON-объектом, недопустимый Idempotency-Key или query-параметр — например, limit=1000 в GET /v1/executions.Исправьте запрос. details перечисляет проблемные поля, если они есть.
PAYLOAD_TOO_LARGE413Тело запроса больше 128 КБ (1 МБ для POST /mcp, чьи инструменты могут передавать схему решения; 32 МБ для POST /v1/decisions/{slug} и POST /v1/hooks/{token}, чьё состояние может содержать файлы).Отправьте тело меньшего размера — для большого состояния отправляйте только поля, нужные вопросам. См. Лимиты.
INVALID_API_KEY401API-ключ отсутствует, имеет неверный формат, неизвестен или отозван.Отправьте Authorization: Bearer <key> с активным ключом.
UNAUTHORIZED401Приложение: вы не вошли, ваша сессия истекла или была завершена — через Выйти на всех устройствах или смену пароля; также неверный e-mail или пароль при входе. URL вебхуков с секретом: у вызова нет корректного Dcision-Signature или Authorization: Bearer whsec_….Войдите снова — или подпишите вызов вебхука текущим секретом.
FORBIDDEN403Вам это недоступно: API-ключ используется вне /v1; рабочее пространство, участником которого вы не являетесь, — тогда details.reason равно "workspace_access"; или действие, которое не разрешает ваша роль, — наблюдатели ничего не могут менять; настройки, ключи провайдеров, секреты и участники требуют администратора; оплата, владение и удаление рабочего пространства требуют владельца.Используйте API-ключи только на /v1. Если дело в роли, обратитесь к администратору или владельцу — в сообщении указана нужная роль.
NOT_FOUND404Приложение: выполнение, API-ключ, шаблон, тариф, сессия оплаты, участник, приглашение, доставка или секрет не существуют в этом рабочем пространстве. URL вебхуков: токен неизвестен, был сменён или вебхук выключен.Проверьте ID — или скопируйте URL вебхука заново на вкладке Дополнительно решения.
CONFLICT409Изменение конфликтует с текущим состоянием: slug уже занят или заблокирован после первой публикации, черновик тем временем сохранил кто-то другой, параллельная публикация или создание, лимит (50 активных API-ключей, 50 секретов, 50 ожидающих приглашений, 10 собственных рабочих пространств), приглашение для того, кто уже в рабочем пространстве, владелец уходит без передачи владения, удаляется рабочее пространство с действующей платной подпиской, подписка уже существует или не существует.Перезагрузите страницу, затем следуйте сообщению.

Решения

КодСтатусЗначениеЧто делать
WORKSPACE_NOT_FOUND404Режим партнёра: заголовок Dcision-Workspace или {ref} не указывает ни на одно подпространство рабочего пространства API-ключа.Отправьте id подпространства или ext:<external_id> — см. подпространства.
SLUG_TAKEN409Режим партнёра: перенос решения в подпространство, где уже есть решение с тем же slug. details содержит decision_id, executions, deliveries и replaceable (копия ни разу не запускалась).При replaceable: true отправьте replace_empty: true, чтобы заменить копию. Иначе сначала переименуйте или удалите решение подпространства.
DECISION_NOT_FOUND404В рабочем пространстве API-ключа нет решения с этим slug, или slug имеет неверный формат.Проверьте slug и то, что ключ принадлежит рабочему пространству решения.
DECISION_NOT_DEPLOYED409Решение существует, но ни разу не публиковалось.Опубликуйте его на вкладке Публикация.
DECISION_DISABLED409Endpoint решения отключён.Нажмите Включить endpoint на его вкладке Публикация.
INVALID_STATE422Состояние не соответствует схеме состояния решения или слишком велико — само по себе или вместе с вопросами для бюджета токенов движка. message называет поле или лимит.Исправьте состояние; для бюджета токенов отправляйте только поля, нужные вопросам. Не повторяйте его без изменений.
INVALID_SCHEMA422Схема решения недействительна — при сохранении или публикации черновика. details перечисляет все проблемы.Исправьте проблемы в редакторе (К ошибке).
IDEMPOTENCY_CONFLICT409Idempotency-Key уже использовался за последние 24 часа с другим запросом — или, с Retry-After: 1, первый запрос с этим ключом ещё выполняется.С Retry-After: подождите и повторите с тем же ключом, чтобы получить сохранённый ответ. Без него: используйте новый ключ для нового запроса — см. Идемпотентность.

Лимиты и оплата

КодСтатусЗначениеЧто делать
RATE_LIMITED429Слишком много запросов вашего рабочего пространства в текущую минуту — или собственные лимиты Playground, или, в приложении, слишком много действий с оплатой (оформление, смена тарифа, портал…), приглашений, кодов входа или попыток входа.Подождите Retry-After секунд, затем повторите — см. Rate limits.
CREDITS_EXHAUSTED402Включённые в тариф решения за период израсходованы, а у рабочего пространства не осталось кредитов.Владелец докупает кредиты или включает автопополнение на странице Оплата (details.billingUrl) либо повышает тариф. Повторы до этого не помогут.
SPEND_CAP_REACHED402Достигнут лимит расходов рабочего пространства за платёжный цикл.Владелец повышает или убирает лимит на странице Оплата, либо дождитесь details.periodEnd.
QUOTA_EXCEEDED402Тариф, настроенный с жёстким лимитом — или без цены за 1 млн решений, — израсходовал все включённые решения за период, поэтому не может продолжать за счёт кредитов.Повысьте тариф или дождитесь details.periodEnd. Повторы раньше не помогут.
PLAN_LIMIT_REACHED402В рабочем пространстве уже максимальное число решений для его тарифа.Удалите решение или повысьте тариф.
PAYMENT_FAILED402Карта была отклонена при смене тарифа.Обновите способ оплаты и попробуйте снова.
BILLING_NOT_CONFIGURED503Этот тариф, период или валюту пока нельзя купить онлайн.Попробуйте позже или напишите на sales@dcision.io.
BILLING_PROVIDER_ERROR502Платёжный провайдер не смог обработать запрос.Попробуйте снова чуть позже.

Движок

Прежде чем вернуть одну из этих ошибок, Dcision уже повторяет временные сбои движка — до 2 повторов в пределах timeoutMs решения. Решение с onEngineError: "fallback" вместо этого отвечает 200 со своим действием fallback — для всех кодов ниже, кроме ENGINE_NOT_CONFIGURED, — см. Настройки решения.

КодСтатусЗначениеЧто делать
ENGINE_NOT_CONFIGURED424У рабочего пространства нет пригодных учётных данных движка: выбран Мой ключ провайдера, но для этого провайдера не сохранён ключ, или ключ движка Dcision недоступен.Добавьте ключ в Настройки → Движок или переключитесь на ключ Dcision.
ENGINE_TIMEOUT504Движок не ответил в пределах timeoutMs решения.Повторите с backoff и тем же Idempotency-Key; если это случается часто, увеличьте timeoutMs.
ENGINE_RATE_LIMITED503Провайдер движка перегружен или упёрся в rate limit, либо у общего ключа движка Dcision не нашлось свободного слота до дедлайна.Повторите с backoff. Со своим ключом проверьте лимиты провайдера.
ENGINE_UNAVAILABLE503Провайдер движка дал сбой или недоступен.Повторите с backoff.
ENGINE_INVALID_REQUEST502Провайдер отклонил запрос; сообщение содержит его причину.Обычно это не временная ошибка: проверьте состояние и модель, затем обратитесь в поддержку с ID запроса.
ENGINE_AUTH_FAILED502Провайдер отклонил ключ движка.Исправьте или замените ключ провайдера в Настройки → Движок.
ENGINE_ERROR502Движок ответил вне контракта решения (ответ отсутствует или неизвестен).Повторите один раз; если ошибка сохраняется, обратитесь в поддержку с ID запроса.

Сервер

КодСтатусЗначениеЧто делать
INTERNAL_ERROR500Непредвиденная ошибка на стороне Dcision.Повторите с backoff; если ошибка сохраняется, обратитесь в поддержку с ID запроса.

Повторные попытки

ПовторятьНе повторять без изменений
429 RATE_LIMITED — после Retry-After400, 401, 403, 404, 413, 422
409 IDEMPOTENCY_CONFLICT с Retry-After — с тем же ключом, после ожиданияЛюбой другой 409
500 INTERNAL_ERROR402 CREDITS_EXHAUSTED, SPEND_CAP_REACHED, QUOTA_EXCEEDED, PLAN_LIMIT_REACHED, PAYMENT_FAILED
503 ENGINE_RATE_LIMITED, ENGINE_UNAVAILABLE424 ENGINE_NOT_CONFIGURED
504 ENGINE_TIMEOUT502 ENGINE_AUTH_FAILED, ENGINE_INVALID_REQUEST
502 ENGINE_ERROR — один раз
Сетевые ошибки и таймауты на вашей стороне

Отправляйте Idempotency-Key, чтобы повтор после потерянного ответа не запустил — и не тарифицировал — решение дважды. Полный клиент приведён в Идемпотентных повторах.

Ошибки никогда не тарифицируются, как и fallback из-за ошибок движка. Недопустимые состояния и сбои движка записываются как выполнения со статусом Ошибка, чтобы их можно было изучить — в приложении или через GET /v1/executions?status=error.

Подробности

Для некоторых кодов details содержит структурированные данные:

422 INVALID_SCHEMA
{
  "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\")." }]
  }
}
402 CREDITS_EXHAUSTED
{
  "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"
    }
  }
}
402 SPEND_CAP_REACHED
{
  "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"
    }
  }
}
403 FORBIDDEN — не участник рабочего пространства
{
  "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_EXHAUSTEDused, included, availableCents (остаток кредита в центах currency — ноль или немного меньше нуля), currency (usd или brl), billingUrl
SPEND_CAP_REACHEDspendCapCents, spentCents (расходы цикла за счёт кредитов, в центах), currency, periodEnd (ISO 8601), billingUrl
QUOTA_EXCEEDEDused, included, periodEnd (ISO 8601), upgradeUrl
PLAN_LIMIT_REACHEDlimit, used, upgradeUrl
FORBIDDEN (доступ к рабочему пространству){ "reason": "workspace_access" } — вы не являетесь (больше не являетесь) участником этого рабочего пространства. Отказы по роли не содержат details.
CONFLICT (устаревший черновик)currentRevision
PAYMENT_FAILEDcode, declineCode от платёжной сети карты

На этой странице