Ошибки

Получить ключ API

Каждая ошибка приходит с HTTP-статусом и одним и тем же JSON-конвертом. code служит контрактом, который читает ваш код; message написан для человека и может меняться.

json
{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid",
    "details": [
      { "field": "targets[0].text", "code": "required", "message": "targets[0].text is required" }
    ],
    "docUrl": "https://www.sofia-post.com/developers/errors#invalid_request",
    "requestId": "2aab5943-6333-4caf-8478-25a85ebd4abf"
  }
}
  • details рассказывает больше: отклонённое поле, причину для сети, исчерпанное окно лимита.
  • docUrl ведёт к объяснению кода на этой странице.
  • requestId идентифицирует запрос: сообщите его в поддержку.

Коды ошибок

СтатусКодЗначение
400invalid_requestТело, запрос или параметр недопустимы. Одна запись на каждое отклонённое поле: field, code (required, is_string, max…) и message.
400invalid_jsonТело не является корректным JSON.
400invalid_cursorКурсор не был возвращён Sofia API.
400webhook_url_invalidАдрес webhook не https или ведёт на частный адрес.
400webhook_event_invalidНеизвестное событие webhook.
400application_name_invalidНастройки › API: название клиента отсутствует или слишком длинное.
400application_profile_invalidНастройки › API: одно из полей профиля клиента недопустимо; в подробностях указано, какое.
400logo_invalidНастройки › API: логотип отклонён (не менее 180×180 px, PNG, JPEG или WebP, не более 2 МБ).
401invalid_tokenТокен отсутствует, неизвестен, истёк или отозван, либо человек, стоящий за ним, потерял права, которые он несёт. См. заголовок WWW-Authenticate.
401unauthorizedТребуется аутентификация.
402subscription_requiredРеальная запись (включая пробный запуск) требует активной подписки или пробного периода.
403insufficient_scopeУ токена нет scope эндпоинта; он указан в деталях.
403insufficient_roleВаша роль в этом Workspace не позволяет это действие.
403live_mode_requiredРеальная запись с тестовым токеном.
403route_closed_to_applicationsЭтот эндпоинт недоступен приложениям.
403forbiddenДоступ запрещён.
403session_requiredНастройки › API: для этого действия нужна сессия Sofia, а не токен.
403impersonation_forbiddenНастройки › API: это действие отклоняется в заимствованной сессии.
403workspace_owner_requiredЭто может сделать только владелец Workspace.
403workspace_member_requiredВы не участник этого Workspace.
404route_not_foundНи один эндпоинт не отвечает на этот метод и путь.
404establishment_not_foundНеизвестное заведение или недоступно этому токену.
404media_not_foundНеизвестное медиа или недоступно этому токену.
404post_not_foundНеизвестная публикация или недоступна этому токену.
404webhook_not_foundНеизвестный webhook или принадлежит другому приложению.
404not_foundРесурс не существует.
404application_not_foundНастройки › API: неизвестный клиент.
404grant_not_foundНеизвестная авторизация или уже отозвана.
404personal_key_not_foundНастройки › API: неизвестный личный ключ.
405method_not_allowedЭтот метод не разрешён для этого эндпоинта.
409post_in_flightСеть отправляет публикацию: повторите удаление чуть позже.
409post_not_editableСеть уже отправила публикацию: её больше нельзя изменить.
409account_already_connectedЭта сеть уже подключена к заведению.
409webhook_limit_reachedУ приложения уже 10 webhook.
409idempotency_in_progressПервый запрос с этим Idempotency-Key ещё выполняется.
409conflictЗапрос противоречит текущему состоянию ресурса.
409scope_removal_forbiddenНастройки › API: разрешение клиента можно добавить, но нельзя удалить.
409public_client_has_no_secretНастройки › API: у публичного клиента нет секрета.
413payload_too_largeФайл превышает лимит загрузки.
415unsupported_media_typeНеподдерживаемый тип содержимого.
422post_refusedСеть, заведение или ваш тариф отклонили бы публикацию. Одна запись на каждую причину, у каждой свой message.
422media_import_refusedНе удалось импортировать медиа по этому URL; причина указана в деталях.
422media_upload_refusedЗагруженный файл не является поддерживаемым изображением или видео.
422platform_not_offeredЭту сеть нельзя подключить.
422idempotency_key_reusedЭтот Idempotency-Key уже использовался с другим телом.
422unprocessable_entityЗапрос понятен, но не может быть обработан.
429rate_limit_exceededОкно лимита заполнено: подождите время из Retry-After.

Причины отклонения публикации

post_refused перечисляет каждую причину в details[].code:

КодЗначение
unsupported_platformЭта сеть не поддерживается.
duplicate_platformОдна и та же сеть указана дважды.
unsupported_formatЭта сеть не предлагает этот формат.
caption_too_longТекст слишком длинный (max, actual).
too_many_hashtagsСлишком много хештегов (max, actual).
too_many_mentionsСлишком много упоминаний (max, actual).
too_many_thread_postsТред слишком длинный (max, actual).
too_many_mediaСлишком много медиа (max, actual).
media_mix_refusedВ этой сети нельзя смешивать фото и видео.
media_requiredЭтой сети нужно фото или видео.
media_type_refusedЭта сеть не принимает этот тип медиа.
scheduled_in_pastscheduledAt находится в прошлом.
scheduled_at_invalidЗапланированной публикации нужен будущий scheduledAt.
account_not_connectedДля этого заведения в этой сети нет подключённого аккаунта.
account_ambiguousВ этой сети подключено несколько аккаунтов: укажите один через accountId.
media_not_foundМедиа нет в медиатеке этого заведения.
media_url_invalidURL медиа должен быть публичным https-адресом.
platform_unavailableЭта сеть ещё не открыта в Sofia.
publication_quota_exceededКвота публикаций вашего тарифа исчерпана.

Обработка ошибок

  • Ветвите логику по code, а не по message.
  • Повторяйте 429 после Retry-After, а 5xx повторяйте с экспоненциальной задержкой.
  • Никогда не повторяйте 4xx без изменений: сначала исправьте запрос.
  • Записывайте requestId при каждой ошибке.