Перейти к содержанию
Sursa для разработчиков

Коды ошибок

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

Формат ошибки

{
  "detail": "…",
  "error": {
    "code": "api.cursor_invalid",
    "message": "The cursor is malformed or was issued for different filters.",
    "details": {"parameter": "cursor"},
    "request_id": "01JB7Q2M4X9V3K8T5N6P0R1S2A",
    "doc_url": "https://developers.sursa.com/errors/api.cursor_invalid"
  }
}

error.code — код с этой страницы; error.request_id совпадает с заголовком X-Request-Id; error.doc_url ведёт на эту страницу.

access_requests

analytics

announcements

answers

api

  • 400api.cursor_invalidкурсор испорчен или выдан для других фильтров
  • 400api.expand_invalidнедопустимый expand[]: {reason}
  • 410api.goneэтот маршрут API выведен из эксплуатации; см. docs/api/CHANGELOG.md
  • 409api.idempotency_in_progressзапрос с этим Idempotency-Key ещё выполняется; повторите позже
  • 400api.idempotency_key_invalidзаголовок Idempotency-Key должен содержать от 1 до 255 печатных символов ASCII
  • 409api.idempotency_mismatchэтот Idempotency-Key уже использован с другим запросом
  • 400api.metadata_invalidmetadata недопустимы: {reason}
  • 404api.not_foundНе найдено
  • 413api.payload_too_largeтело запроса слишком большое
  • 429api.quota_exceededорганизация исчерпала квоту запросов к API на этот период
  • 429api.rate_limitedслишком много запросов; повторите позже

api_keys

api_logs

  • 404api_logs.not_foundзапрос не найден в журнале API или старше 14 дней

auth

authz

billing

  • 402billing.seats_exceededВсе {purchased} мест подписки заняты ({reserved} — активные пользователи и ожидающие приглашения). Чтобы пригласить ещё людей, добавьте места на странице «Тариф».

cards

  • 400cards.archive_emptyв архиве нет поддерживаемых документов
  • 400cards.archive_encryptedархив зашифрован; загрузите архив без пароля
  • 400cards.archive_invalidфайл не является ZIP-архивом или архив повреждён
  • 404cards.archive_job_not_foundзадание распаковки архива не найдено
  • 413cards.archive_too_largeраспакованный архив больше допустимого
  • 413cards.archive_too_many_filesв архиве больше файлов, чем допустимо
  • 400cards.bulk_invalid{reason}
  • 403cards.category_whole_accessкатегорию можно изменить только при доступе ко всему документу
  • 404cards.comment_not_foundкомментарий не найден или он не ваш
  • 403cards.content_whole_accessсодержимое карточки можно заменить только при доступе ко всему документу
  • 403cards.delete_whole_accessкарточку можно удалить только при доступе ко всему документу
  • 403cards.duplicate_restrictedсуществует такой же документ, который недоступен целиком при вашем профиле доступа к данным
  • 400cards.export_formatformat должен быть pdf, docx или md
  • 409cards.external_id_takenexternal_id «{external_id}» уже использует другая карточка организации
  • 409cards.indexing_in_progressкарточка сейчас индексируется
  • 400cards.invalid_folder_filterдля folder=none нужен параметр collection
  • 400cards.invalid_kind_filterkind должен быть одним из ('file', 'text', 'connector')
  • 400cards.invalid_orderorder должен быть 'asc' или 'desc'
  • 400cards.invalid_owner_filterowner должен быть 'me', 'none' или ID пользователя
  • 400cards.invalid_sortsort должен быть одним из ('created_at', 'updated_at', 'title', 'size', 'verified_at', 'trust', 'due')
  • 400cards.invalid_status_filterstatus должен быть одним из ('processing', 'ready', 'error', 'archived', 'all')
  • 400cards.invalid_type_filtertype должен быть 'table' или 'text'
  • 400cards.invalid_verification_filterverification должен быть одним из ('verified', 'needs_verification', 'stale')
  • 409cards.managed_by_sourceэтой карточкой управляет источник; измените документ в источнике (для своего источника — отправьте его заново)
  • 403cards.no_accessнет доступа {action} к этой карточке
  • 409cards.no_original_fileоригинальный файл для этой карточки не хранится
  • 404cards.not_foundкарточка не найдена
  • 400cards.review_requires_asyncдля review=true нужен async=true: предпросмотр разбора показывается, пока задание ждёт
  • 403cards.sensitivity_admin_onlyтолько администратор может понизить чувствительность или переместить чувствительную карточку
  • 404cards.table_not_foundтаблица не найдена
  • 400cards.unknown_table_partнеизвестная таблица «{table_id}»
  • 415cards.unsupported_formatформат {ext} не поддерживается; допустимые: ['.adoc', '.asciidoc', '.bmp', '.csv', '.docx', '.eml', '.htm', '.html', '.jpeg', '.jpg', '.markdown', '.md', '.ods', '.pdf', '.png', '.pptx', '.tif', '.tiff', '.tsv', '.txt', '.webp', '.xls', '.xlsm', '.xlsx']
  • 403cards.verify_forbiddenподтвердить эту карточку может только владелец, верификатор или администратор
  • 400cards.verify_user_account_requiredдля верификации нужна учётная запись пользователя, а не ключ API
  • 404cards.version_not_foundверсия не найдена

catalog

categories

collections

  • 403collections.admin_fieldsдля настроек доступа, чувствительности, значений по умолчанию и настроек поиска коллекции нужна роль администратора
  • 409collections.index_outdatedиндекс этой коллекции устарел; сначала обновите его: PATCH /v1/collections/{name} с upgrade_index: true переиндексирует коллекцию
  • 409collections.indexing_in_progressдокументы этой коллекции сейчас индексируются; измените настройки поиска, когда индексация завершится
  • 400collections.invalid_nameнедопустимое название коллекции: 1-64 символа, латинские буквы, цифры, «_» и «-»
  • 403collections.no_accessнет доступа «{action}» к коллекции «{name}»
  • 403collections.no_write_accessнет доступа на запись к коллекции «{name}»
  • 404collections.not_foundколлекция «{name}» не найдена

comments

conversations

drafts

  • 409drafts.already_requestedпубликация этого черновика уже запрошена; пока запрос ждёт проверки, черновик можно продолжать редактировать
  • 409drafts.card_deletedкарточка этого черновика удалена
  • 409drafts.card_publishedкарточку опубликовали или изменили после начала этого черновика; начните новый черновик с опубликованной версии
  • 422drafts.content_json_invalidcontent_json должен быть объектом с schemaVersion (строка) и doc (объект), не больше 500000 байт
  • 409drafts.deleted_by_collaboratorдругой соавтор удалил этот черновик; чтобы продолжить редактирование, начните новый черновик
  • 409drafts.existsу вас уже есть черновик этой карточки
  • 422drafts.invalid_scopescope должен быть mine, all или orphaned
  • 403drafts.not_collaboratorизменить этот черновик может только соавтор или администратор
  • 404drafts.not_foundчерновик не найден
  • 409drafts.not_requestedпубликация этого черновика не запрашивалась
  • 403drafts.publish_forbiddenу вас нет права публиковать в эту коллекцию
  • 422drafts.scheduled_pastзапланированная дата должна быть в будущем
  • 422drafts.title_requiredнужен заголовок

events

  • 404events.not_foundсобытие не найдено или старше 30 дней

files

  • 410files.expiredсрок хранения файла истёк
  • 422files.infectedфайл {filename} отклонён антивирусом: {signature}
  • 422files.invalid_expiry_filterexpiry должен быть одним из active, expiring, expired
  • 422files.invalid_kind_filterkind должен быть одним из pdf, xlsx, csv, docx, md
  • 422files.invalid_origin_filterorigin должен быть одним из answer, card, insights, list
  • 409files.no_expiryэтот файл хранится бессрочно
  • 404files.not_foundфайл не найден
  • 409files.not_regenerable{reason}
  • 422files.preview_failedне удаётся показать предпросмотр этого файла: {reason}
  • 404files.regeneration_requiredэтот файл собран на основном адресе и содержит сведения, которые адрес API не возвращает; пересоздайте его через POST /v1/files/{file_id}/regenerate или скачайте на основном адресе
  • 409files.removedфайл уже удалён по истечении срока хранения; пересоздайте его
  • 503files.scan_unavailableантивирусная проверка недоступна; повторите позже
  • 413files.too_largeфайл {filename} больше лимита загрузки {limit}
  • 415files.type_mismatchфайл {filename} не соответствует своему типу: расширение {extension}, объявленный тип {declared}, содержимое {detected}

finance

folders

  • 400folders.appearance_invalidcolor должен быть одним из blue, violet, emerald, amber, orange, rose, cyan, slate; icon — ключом категории или lock
  • 400folders.card_collection_mismatchкарточка и папка принадлежат разным коллекциям
  • 409folders.cycleпапку нельзя переместить в неё саму или в её подпапку
  • 409folders.depth_exceededитоговая глубина папок превышает максимум в 3 уровня
  • 404folders.not_foundпапка не найдена
  • 400folders.parent_mismatchродительская папка принадлежит другой коллекции
  • 400folders.sibling_not_foundprev_sibling_id должен быть 'first', 'last' или ID соседней папки в целевом родителе
  • 400folders.title_invalidназвание папки должно быть длиной от 1 до 200 символов

insights

internal

jobs

  • 409jobs.already_processingзадание уже обрабатывается, и убрать его из очереди больше нельзя
  • 409jobs.cancel_failedне удалось убрать задание из очереди
  • 410jobs.cancel_unsupportedзадание поставлено в очередь до появления отмены; дождитесь его завершения
  • 422jobs.invalid_filter{reason}
  • 404jobs.not_foundзадание не найдено
  • 409jobs.not_queuedубрать из очереди можно только задания в очереди (статус этого задания — {status})

limits

  • 402limits.cardsОрганизация достигла лимита в {limit} карточек{plan}. Удалите ненужные карточки или попросите системного администратора повысить лимит.
  • 429limits.concurrent_answersв организации уже формируется {used} ответов (лимит {limit}); повторите через несколько секунд
  • 429limits.questionsОрганизация исчерпала лимит в {limit} вопросов за 24 часа{plan}. Вопросы снова станут доступны примерно через {wait}. Если нужно больше, попросите системного администратора повысить лимит.
  • 402limits.sourcesОрганизация достигла лимита в {limit} источников{plan}. Удалите ненужные источники или попросите системного администратора повысить лимит.
  • 402limits.sources_instantМгновенные обновления не входят в тариф организации{plan}; источник остаётся на расписании.
  • 402limits.storageНедостаточно места в хранилище: организация использует {used} из {limit} ГБ{plan}, а этому файлу нужно ещё {amount}. Удалите ненужные карточки или файлы или попросите системного администратора повысить лимит.
  • 402limits.usersОрганизация достигла лимита в {limit} пользователей{plan} с учётом активных пользователей и ожидающих приглашений. Деактивируйте ненужные учётные записи или отзовите приглашения либо попросите системного администратора повысить лимит.

notifications

oauth

  • 403oauth.operation_not_allowedэта операция недоступна токену OAuth-приложения
  • 401oauth.token_expiredсрок действия токена доступа истёк; получите новый с помощью токена обновления

oauth_apps

  • 400oauth_apps.invalid{reason}
  • 400oauth_apps.invalid_redirect_uriадрес возврата «{uri}» не допускается: используйте https, http — только для localhost, или схему приложения в форме обратного домена, без фрагмента
  • 400oauth_apps.invalid_scopeнеизвестная область доступа «{scope}»
  • 409oauth_apps.not_confidentialприложение публичное: у него нет секрета клиента и доступа по client credentials
  • 404oauth_apps.not_foundOAuth-приложение не найдено
  • 409oauth_apps.too_manyу организации уже {max} OAuth-приложений

oauth_authorizations

org

  • 403org.deletedэта организация удалена
  • 404org.not_foundорганизация не найдена
  • 403org.suspendedэта организация приостановлена: вход закрыт, данные сохраняются; обратитесь к администратору

profiles

  • 400profiles.unknownнеизвестный профиль доступа «{key}»

quality

query

questions

sources

tasks

  • 400tasks.invalid_scopescope должен быть 'mine' или 'team'
  • 403tasks.team_forbiddenпредставление команды доступно администраторам и верификаторам
  • 400tasks.user_account_requiredличные задачи есть только у учётных записей пользователей, а не у ключей API

uploads

users

  • 422users.display_name_emptyотображаемое имя не может быть пустым
  • 409users.email_takenпользователь с этим e-mail уже есть в организации
  • 400users.inactive_assignmentнеактивного пользователя нельзя назначить
  • 409users.last_adminв организации должен остаться хотя бы один активный администратор
  • 409users.managed_by_scimэтой учётной записью управляет ваш провайдер идентификации (SCIM); меняйте её там
  • 404users.not_foundпользователь не найден
  • 400users.not_in_orgпользователь не найден в организации
  • 400users.offboard_targetполучателем передачи должен быть активный пользователь той же организации, кроме увольняемого
  • 403users.password_not_allowedэта учётная запись входит через вашего провайдера идентификации и не имеет пароля; администратор может добавить пароль ссылкой для сброса
  • 400users.unknown_or_inactiveнеизвестные или неактивные пользователи: {ids}
  • 400users.update_invalid{reason}
  • 409users.username_takenпользователь с этим именем пользователя уже есть в организации

users_import

validation

verification

view_as

  • 403view_as.admin_key_requiredдля X-View-As нужен ключ API с ролью admin
  • 400view_as.invalid_headerX-View-As должен иметь вид <profile>[:viewer|verifier|editor] с существующим профилем
  • 403view_as.read_onlyрежим просмотра: изменения отключены, пока вы смотрите от имени другого профиля

webhooks

  • 400webhooks.access_invalidнедопустимы роль вебхука, режим тела доставки, профиль доступа, коллекции или теги
  • 400webhooks.auth_invalidавторизация исходящих запросов должна быть bearer с токеном или basic с именем пользователя и паролем
  • 403webhooks.collections_outside_keyэтот ключ API ограничен коллекциями: укажите collection_ids вебхука, и все они должны входить в коллекции ключа
  • 404webhooks.delivery_not_foundдоставка вебхука не найдена
  • 400webhooks.description_too_longописание вебхука длиннее 200 символов
  • 409webhooks.endpoint_disabledвебхук отключён; сначала включите его
  • 409webhooks.event_not_permittedвебхук сейчас не получил бы это событие: его роль, профиль доступа, коллекции или теги больше этого не разрешают, поэтому доставка не повторяется
  • 400webhooks.events_requiredподпишитесь хотя бы на одно событие
  • 403webhooks.feature_disabledвебхуки не входят в тариф организации
  • 400webhooks.headers_invalidнедопустимые собственные заголовки вебхука: не больше 10 заголовков, имена из букв, цифр и дефисов без зарезервированных имён, значения до 1024 байт
  • 400webhooks.invalid_urlurl вебхука должен быть абсолютным адресом https без учётных данных
  • 404webhooks.not_foundвебхук не найден
  • 400webhooks.overlap_invalidперекрытие при смене секрета должно быть от 0 до 168 часов
  • 400webhooks.private_addressхост вебхука разрешается в частный или зарезервированный сетевой адрес
  • 400webhooks.redeliver_invalidпериод повторной доставки должен быть в пределах последних 30 дней, since — раньше until, а статусы — success, exhausted или cancelled
  • 409webhooks.too_manyу организации может быть не больше 20 вебхуков
  • 400webhooks.unknown_eventнеизвестное событие вебхука {type}
  • 400webhooks.unresolvableхост вебхука не разрешается