Ошибки

Любой ответ 4xx/5xx — application/problem+json (RFC 9457):

{
  "type": "https://docs.solved.group/errors/insufficient_credits",
  "title": "Not enough credits",
  "status": 402,
  "detail": "This operation costs 43 credits; balance is 12.",
  "code": "insufficient_credits",
  "request_id": "req_01J9Z4A7R3V5W2XN4V6B0RTC5H",
  "retryable": false,
  "meta": { "required_credits": 43, "balance": 12 }
}

Ветвитесь по code, не по title и не по status. code — единственное поле со стабильной гарантией, title — человеческое описание и может переформулироваться. retryable говорит, можно ли повторить этот же запрос с тем же Idempotency-Key. request_id совпадает с заголовком X-Request-ID — указывайте его, когда просите разобрать конкретный сбой.

Ошибки валидации добавляют errors[] с указанием на поле:

"errors": [{ "field": "/destination_url", "code": "invalid_url", "detail": "Not a valid absolute URL." }]

Частые коды:

code	HTTP	retryable	значение
`validation_failed`	422	нет	тело не прошло валидацию схемы
`unauthenticated`	401	нет	нет credential или он невалиден
`insufficient_scope`	403	нет	ключу/сессии не хватает scope
`insufficient_credits`	402	нет	не хватает баланса — пополните и повторите
`rate_limited`	429	да	снизьте частоту; см. `Retry-After`
`idempotency_in_progress`	409	да	тот же ключ ещё выполняется, повторите позже
`idempotency_key_reused`	422	нет	тот же ключ, другое тело запроса — возьмите новый ключ

Полный реестр, по всем платформенным и продуктовым кодам — /errors (генерируется из спецификации, I2, SOL-6629).

В MCP та же информация приходит как результат инструмента с isError: true и блоком structuredContent (error_code, retry_eligible, message) вместо protocol-level ошибки — агент видит сбой и может на него отреагировать.

Далее: Лимиты · Идемпотентность