Формат ошибок API и коды ошибок

Каждый ответ API с ошибкой имеет один и тот же формат. Ваш код должен опираться на код ошибки в поле error, а не на текст в message: код стабилен, а текст может меняться и переводится на язык аккаунта.

#Структура ответа с ошибкой

{
  "error": "validation_failed",
  "message": "Some of the information provided is invalid. Please check and try again.",
  "details": [
    { "field": "title", "reason": "minLength", "message": "…" }
  ],
  "request_id": "6b1f0c2e-…"
}

error

Машиночитаемый код, например not_found. Для большинства ошибок он также передаётся в заголовке X-Error-Code — но опирайтесь на поле в теле.

message

Описание для человека на языке аккаунта: с API-ключом – владельца рабочего пространства, с подключённым приложением – того, кто его подключил. Без действительного токена – например, при 401 из проверки токена – язык следует Accept-Language, иначе текст на английском. Заголовок Content-Language называет язык.

details

Есть, только когда нужно сообщить что-то ещё. Для 422 из проверки входных данных это список с field, reason и message для каждой проблемы; для 422 из бизнес-логики и всех остальных ошибок — объект, например с reason, retry_after_sec или списком issues. При превышении размера в нём есть field, reason и limit, а для 413 request_too_large — max_bytes и max_kb. Поэтому проверяйте, является ли details списком.

request_id

ID запроса. Он также передаётся в заголовке X-Request-Id. Указывайте его, когда обращаетесь в поддержку.

Исключения: в ответе 429 rate_limited вместо details есть поле retry_after_sec; при 429 и 403 insufficient_scope в теле нет request_id. У 401 из проверки токена и 422 из проверки схемы нет заголовка X-Error-Code; при проверке схемы переводится только message верхнего уровня, тексты внутри details остаются на английском. Заголовок X-Request-Id есть всегда.

#Самые важные коды

#Как читать ошибки во входных данных

При 422 validation_failed details перечисляет каждую проблему отдельно: field — путь к полю (со слешами для вложенных объектов, например theme_config/button_style), reason — нарушенное правило, например required, minLength, maxLength, enum или additionalProperties. При additionalProperties в message сказано, какие поля неизвестны, — часто это опечатка в имени поля.

#Рекомендуемая обработка в коде

• 400, 413 и 422: не повторяйте, а исправьте запрос
• 401 invalid_token: один раз получите новый токен и повторите
• 403: не повторяйте; проверьте область доступа, тариф или то, кому разрешено это действие
• 404: проверьте ID; после удаления это нормально
• 409: загрузите состояние заново и решите, нужно ли ещё это действие
• 429: подождите столько, сколько указано в Retry-After, затем повторите — см. Лимиты запросов
• 500 и 503: повторите несколько раз с растущими паузами