Error codes

Every error response has the same shape. Rely on the HTTP status and error.code; error.message is a readable English text and may change.

Error format

{
  "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 is the code on this page; error.request_id matches the X-Request-Id header; error.doc_url links to this page.

access_requests

409access_requests.closeda decision has already been made on this access request
400access_requests.invalid{reason}
404access_requests.not_foundaccess request or answer not found
403access_requests.not_personaccess requests are available only to users, not to API keys or in view-as mode

analytics

403analytics.admins_onlyanalytics is available to organization administrators only
422analytics.invalid_periodinvalid period: {reason}

announcements

422announcements.audience_requiredselect at least one group or user
403announcements.author_onlyonly the author can do this
422announcements.invalid_viewview must be inbox, my_sent, all_sent or my_scheduled
404announcements.not_foundannouncement not found
409announcements.not_sentthe announcement has not been sent yet
422announcements.note_too_longthe note must be 700 characters or less
422announcements.scheduled_pastthe send date must be in the future

answers

400answers.empty_questionempty question
429answers.engine_busythe answer service is busy; try again in {retry_after} s
409answers.external_ai_disabledexternal processing is disabled for the organization, and this answer cannot be produced without it
400answers.last_message_not_userthe last message must be from the user
404answers.no_collectionsno readable collections
422answers.scope_invalidthe question scope cannot be applied: {reason}

api

400api.cursor_invalidthe cursor is malformed or was issued for different filters
400api.expand_invalidexpand[] is invalid: {reason}
410api.gonethis API route has been retired; see docs/api/CHANGELOG.md
409api.idempotency_in_progressa request with this Idempotency-Key is still in progress; retry later
400api.idempotency_key_invalidthe Idempotency-Key header must be 1 to 255 printable ASCII characters
409api.idempotency_mismatchthis Idempotency-Key was already used with a different request
400api.metadata_invalidmetadata is invalid: {reason}
404api.not_foundNot Found
413api.payload_too_largerequest body is too large
429api.quota_exceededthe organization has used its API request quota for this period
429api.rate_limitedtoo many requests; try again later

api_keys

400api_keys.data_profile_not_applicabledata_profile does not apply to the admin role; an admin key sees all data of the organization
401api_keys.expiredthe API key has expired
403api_keys.feature_disabledAPI tokens are not included in the organization's plan
400api_keys.invalid_cidrsallowed_cidrs must be a list of networks such as 10.0.0.0/8: {reason}
400api_keys.invalid_collectionscollection_ids must list collections of the organization: {reason}
400api_keys.invalid_expiresexpires_at must be a future moment in ISO 8601
400api_keys.invalid_scopesscopes must be a list of read, write, admin, system: {reason}
403api_keys.ip_not_allowedrequests with this API key are not allowed from this network
403api_keys.mcp_onlya personal MCP key works only on the /mcp endpoint
404api_keys.not_foundkey not found
403api_keys.scopethe API key has no {scope} scope

api_logs

404api_logs.not_foundrequest not found in the API log or older than 14 days

auth

403auth.admin_requiredadmin role required
403auth.editor_requirededitor role required
401auth.not_authenticatednot authenticated
403auth.system_scopesystem administrators have no access to organization data

authz

403authz.forbiddenpermission '{permission}' required
400authz.group_key_invalidinvalid group key: latin letters, digits, '_' and '-', up to 80 characters, starting with a letter
409authz.group_key_takengroup key '{key}' is already used
409authz.group_kind_immutablethis group is built in; its members are computed and cannot be edited, and it cannot be deleted
409authz.group_managed_externallythe group is managed by the identity provider (SCIM)
404authz.group_not_foundgroup not found
409authz.last_ownerat least one '{role}' must remain on the object
409authz.legacy_admin_single_user_onlythe admin role is granted to users only, not to groups
409authz.managed_by_sourcethe permissions of this object are managed by its source
400authz.role_key_invalidinvalid role key: latin letters, digits, '_' and '-', up to 64 characters, starting with a letter
409authz.role_key_takenrole key '{key}' is already used
404authz.role_not_foundrole not found
400authz.role_scope_mismatchrole '{key}' cannot be granted on {object_type}
409authz.role_system_immutablesystem roles cannot be changed or deleted
400authz.subject_requiredexactly one of group_id and user_id is required
400authz.unknown_permissionunknown permission '{permission}'
400authz.user_not_in_orguser not found in the organization
400authz.view_requireda role for objects must include COLLECTION_VIEW

billing

402billing.seats_exceededAll {purchased} seats of the subscription are taken ({reserved} active users and pending invitations). Add seats on the Billing page to invite more people.

cards

400cards.archive_emptythe archive contains no supported documents
400cards.archive_encryptedthe archive is encrypted; upload an archive without a password
400cards.archive_invalidthe file is not a zip archive or the archive is damaged
404cards.archive_job_not_foundarchive unpacking job not found
413cards.archive_too_largethe unpacked archive is larger than allowed
413cards.archive_too_many_filesthe archive contains more files than allowed
400cards.bulk_invalid{reason}
403cards.category_whole_accessthe category can be changed only with access to the whole document
404cards.comment_not_foundcomment not found or not yours
403cards.content_whole_accessthe content of the card can be replaced only with access to the whole document
403cards.delete_whole_accessthe card can be deleted only with access to the whole document
403cards.duplicate_restrictedan identical document exists that is not fully available with your data access profile
400cards.export_formatformat must be pdf, docx or md
409cards.external_id_takenexternal_id '{external_id}' is already used by another card of the organization
409cards.indexing_in_progressthe card is being indexed right now
400cards.invalid_folder_filterfolder=none requires the collection parameter
400cards.invalid_kind_filterkind must be one of ('file', 'text', 'connector')
400cards.invalid_orderorder must be 'asc' or 'desc'
400cards.invalid_owner_filterowner must be 'me', 'none' or a user id
400cards.invalid_sortsort must be one of ('created_at', 'updated_at', 'title', 'size', 'verified_at', 'trust', 'due')
400cards.invalid_status_filterstatus must be one of ('processing', 'ready', 'error', 'archived', 'all')
400cards.invalid_type_filtertype must be 'table' or 'text'
400cards.invalid_verification_filterverification must be one of ('verified', 'needs_verification', 'stale')
409cards.managed_by_sourcethis card is managed by a source; change the document in the source (for a custom source, push it again)
403cards.no_accessno {action} access to this card
409cards.no_original_filethe original file is not stored for this card
404cards.not_foundcard not found
400cards.review_requires_asyncreview=true requires async=true: the parsing preview is shown while the job waits
403cards.sensitivity_admin_onlyonly an administrator can lower the sensitivity or move a sensitive card
404cards.table_not_foundtable not found
400cards.unknown_table_partunknown table '{table_id}'
415cards.unsupported_formatformat {ext} is not supported; allowed: ['.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_forbiddenonly the owner, a verifier or an admin can verify this card
400cards.verify_user_account_requiredverification requires a user account, not an API key
404cards.version_not_foundversion not found

catalog

404catalog.icon_not_foundthe service has no icon
404catalog.service_not_foundunknown service '{service_id}'

collections

403collections.admin_fieldsadmin role required for access settings, sensitivity, defaults and the search settings of the collection
409collections.index_outdatedthe index of this collection is outdated; update it first: PATCH /v1/collections/{name} with upgrade_index: true re-indexes the collection
409collections.indexing_in_progressdocuments of this collection are being indexed right now; change the search settings when indexing finishes
400collections.invalid_nameinvalid collection name: 1-64 characters, latin letters, digits, '_' and '-'
403collections.no_accessno '{action}' access to collection '{name}'
403collections.no_write_accessno write access to collection '{name}'
404collections.not_foundcollection '{name}' not found

comments

422comments.body_requiredcomment text is required
403comments.forbiddenyou cannot change this comment
404comments.not_foundcomment not found
400comments.reply_to_replyreplies are allowed only to a root comment
409comments.resolved_edita resolved comment cannot be edited

conversations

422conversations.invalid_cursorinvalid cursor
404conversations.not_foundconversation not found
422conversations.title_emptytitle must not be empty

drafts

409drafts.already_requesteda publishing request has already been made for this draft; you can keep editing while it awaits review
409drafts.card_deletedthe card of this draft was deleted
409drafts.card_publishedthe card was published or changed after this draft was started; start a new draft from the published version
422drafts.content_json_invalidcontent_json must be an object with schemaVersion (string) and doc (object), 500000 bytes at most
409drafts.deleted_by_collaboratoranother collaborator deleted this draft; start a new draft to continue editing
409drafts.existsyou already have a draft of this card
422drafts.invalid_scopescope must be mine, all or orphaned
403drafts.not_collaboratoronly a collaborator or an administrator can change this draft
404drafts.not_founddraft not found
409drafts.not_requestedpublishing has not been requested for this draft
403drafts.publish_forbiddenyou do not have permission to publish to this collection
422drafts.scheduled_pastthe scheduled date must be in the future
422drafts.title_requiredtitle is required

events

404events.not_foundevent not found or older than 30 days

files

410files.expiredfile has expired
422files.infectedthe file {filename} was rejected by the antivirus: {signature}
422files.invalid_expiry_filterexpiry must be one of active, expiring, expired
422files.invalid_kind_filterkind must be one of pdf, xlsx, csv, docx, md
422files.invalid_origin_filterorigin must be one of answer, card, insights, list
409files.no_expirythis file is kept without an expiry date
404files.not_foundfile not found
409files.not_regenerable{reason}
422files.preview_failedcannot preview this file: {reason}
404files.regeneration_requiredthis file was built at the main address and holds details the API address does not return; regenerate it with POST /v1/files/{file_id}/regenerate or download it at the main address
409files.removedthe file was already removed after its expiry; regenerate it instead
503files.scan_unavailablethe antivirus check is unavailable; try again later
413files.too_largethe file {filename} is larger than the upload limit of {limit}
415files.type_mismatchthe file {filename} does not match its type: extension {extension}, declared type {declared}, content {detected}

finance

503finance.engine_unavailablethe assistant is unavailable: {reason}
413finance.export_too_largethe export has more than {limit} rows: narrow the filters
403finance.forbiddenyour data profile has no access to financial data
400finance.invalid{reason}

folders

400folders.appearance_invalidcolor must be one of blue, violet, emerald, amber, orange, rose, cyan, slate; icon must be a category key or lock
400folders.card_collection_mismatchthe card and the folder belong to different collections
409folders.cyclea folder cannot be moved into itself or its subfolder
409folders.depth_exceededresulting folder depth exceeds maximum of 3
404folders.not_foundfolder not found
400folders.parent_mismatchparent folder belongs to another collection
400folders.sibling_not_foundprev_sibling_id must be 'first', 'last' or the id of a sibling folder in the target parent
400folders.title_invalidfolder title must be 1 to 200 characters

insights

403insights.finance_forbiddenyour data profile has no access to financial data
400insights.invalid_period{name}: period must look like YYYY-MM, got '{value}'
404insights.no_datano tabular data for insights
400insights.period_ordersince must not be later than until

internal

500internal.errorinternal server error

jobs

409jobs.already_processingthe job is already being processed and can no longer be removed from the queue
409jobs.cancel_failedthe job could not be removed from the queue
410jobs.cancel_unsupportedthe job was queued before cancellation was supported; wait until it finishes
422jobs.invalid_filter{reason}
404jobs.not_foundjob not found
409jobs.not_queuedonly queued jobs can be removed from the queue (this job is {status})

limits

402limits.cardsThe organization has reached its limit of {limit} cards{plan}. Delete cards you no longer need or ask the system administrator to raise the limit.
429limits.concurrent_answersthe organization already has {used} answers in progress (limit {limit}); try again in a few seconds
429limits.questionsThe organization has used its limit of {limit} questions per 24 hours{plan}. Questions will be available again in about {wait}. Ask the system administrator to raise the limit if you need more.
402limits.sourcesThe organization has reached its limit of {limit} sources{plan}. Delete sources you no longer need or ask the system administrator to raise the limit.
402limits.sources_instantInstant updates are not included in the organization's plan{plan}; the source stays on schedule.
402limits.storageNot enough storage: the organization uses {used} of {limit} GB{plan}, and this file needs {amount} more. Delete cards or files you no longer need or ask the system administrator to raise the limit.
402limits.usersThe organization has reached its limit of {limit} users{plan}, counting active users and pending invitations. Deactivate accounts or revoke invitations you no longer need, or ask the system administrator to raise the limit.

notifications

422notifications.invalid_filter{reason}

oauth

403oauth.operation_not_allowedthis operation is not available to an OAuth app token
401oauth.token_expiredthe access token has expired; get a new one with the refresh token

oauth_apps

400oauth_apps.invalid{reason}
400oauth_apps.invalid_redirect_uriredirect URI '{uri}' is not allowed: use https, http only for localhost, or a reverse-domain app scheme, without a fragment
400oauth_apps.invalid_scopeunknown scope '{scope}'
409oauth_apps.not_confidentialthe app is public: it has no client secret and no client credentials access
404oauth_apps.not_foundOAuth app not found
409oauth_apps.too_manythe organization already has {max} OAuth apps

oauth_authorizations

404oauth_authorizations.not_foundapp authorization not found

org

403org.deletedthis organization has been deleted
404org.not_foundorganization not found
403org.suspendedthis organization is suspended: sign-in is closed, the data is kept; contact your administrator

profiles

400profiles.unknownunknown data profile '{key}'

quality

400quality.filter_invalid{reason}
409quality.followup_closedthe knowledge gap is already closed
404quality.followup_not_foundknowledge gap in progress not found

query

422query.invalid_dateinvalid date: {value}

questions

400questions.answer_emptythe answer is empty and cannot be saved as a card
404questions.answer_table_not_foundtable not found in the answer
404questions.dataset_not_founddataset not found
400questions.export_formatformat must be one of pdf, xlsx, csv, docx, md
400questions.export_rowsrows must list table row numbers from 0, comma-separated, ranges with a hyphen (0-4,7)
422questions.invalid_feedback_filterfeedback must be positive, negative, rated, none or unanswered
422questions.invalid_q_fieldq_field must be all or question
422questions.invalid_view_as_filterview_as must be only or exclude
404questions.not_foundquestion not found
400questions.save_card_error{reason}

sources

400sources.connection_kind_mismatchthe connection is for {kind}, not for this source
404sources.connection_not_foundsource connection not found
403sources.connection_not_usablethis connection belongs to another user or is disabled
403sources.feature_disabledone-click source connectors are not included in the organization's plan
400sources.folder_invalidthe folder is not in the source collection or you cannot add cards to it
400sources.invalid_configinvalid source settings: {reason}
400sources.kind_not_allowed_for_keyan API key can create and change only custom sources; connect other sources in the browser
404sources.not_foundsource not found
422sources.push_batch_rejectedthe batch was not applied because some documents were rejected; see details.results
400sources.push_document_invalid{reason}
404sources.push_document_not_founddocument not found in the source
409sources.push_initial_requiredcomplete an initial synchronization before an incremental one
401sources.push_key_invalidthe source API key is missing, invalid or revoked
404sources.push_key_not_foundsource API key not found
409sources.push_sync_closedthe synchronization is closed or expired; open a new one
404sources.push_sync_not_foundsynchronization not found
409sources.push_sync_openanother synchronization is open for this source; close it or wait until it expires
409sources.push_too_many_documentsthe source has reached the document limit of your plan
400sources.push_unsupportedthis source does not accept pushed documents (only custom sources do)

tasks

400tasks.invalid_scopescope must be 'mine' or 'team'
403tasks.team_forbiddenthe team view is available to administrators and verifiers
400tasks.user_account_requiredpersonal tasks belong to user accounts, not API keys

uploads

409uploads.already_usedthe upload has already been used
422uploads.checksum_mismatchthe SHA-256 checksum does not match ({reason})
410uploads.expiredthe upload has expired
409uploads.incompletethe upload is missing {missing_count} parts
404uploads.not_foundupload not found
409uploads.not_readythe upload is not ready yet (status {status})
400uploads.part_invalidupload part {n} is invalid: {reason}
422uploads.purpose_mismatchthe upload was created for {purpose}, not for {expected}
422uploads.rejectedthe upload was rejected: {reason}
409uploads.state_conflictthe upload does not accept this operation in status {status}
503uploads.storage_unavailablethe file storage is temporarily unavailable; try again later
413uploads.too_largethe file is larger than the upload limit of {limit_bytes} bytes
415uploads.unsupported_formatfiles with extension {extension} cannot be uploaded for {purpose}

users

422users.display_name_emptydisplay name cannot be empty
409users.email_takena user with this e-mail already exists in the organization
400users.inactive_assignmentan inactive user cannot be assigned
409users.last_adminthe organization must keep at least one active administrator
409users.managed_by_scimthis account is managed by your identity provider (SCIM); change it there
404users.not_founduser not found
400users.not_in_orguser not found in the organization
400users.offboard_targettransfer target must be an active user of the same organization other than the offboarded one
403users.password_not_allowedthis account signs in through your identity provider and has no password; an administrator can add one with a reset link
400users.unknown_or_inactiveunknown or inactive users: {ids}
400users.update_invalid{reason}
409users.username_takena user with this username already exists in the organization

users_import

422users_import.csv_invalidthe file is not a valid CSV: {reason}
422users_import.emptythe file has no rows after the header
422users_import.no_email_columnthe header has no e-mail column (email, e-mail, mail); found: {columns}
413users_import.too_many_rowsthe file has {rows} rows; import at most {limit} rows at a time

validation

422validation.failedrequest validation failed

verification

409verification.absolute_expiredthe verification date has passed: schedule a new verification interval before verifying
409verification.archivedthe card is archived
400verification.date_requireda date in the future is required
422verification.invalid_actionkind must be view or copy
400verification.invalid_intervalverification interval must be between 1 and 3650 days
422verification.invalid_modemode must be up_first or all
400verification.invalid_reasonreason must be manual, automation or requested
422verification.invalid_sortunknown sort field or order
400verification.invalid_typeverification type must be relative, absolute or manual
409verification.self_remindyou are the only verifier of this card: there is nobody to remind
400verification.verifier_requiredat least one verifier is required

view_as

403view_as.admin_key_requiredX-View-As requires an API key with the admin role
400view_as.invalid_headerX-View-As must be <profile>[:viewer|verifier|editor] with an existing profile
403view_as.read_onlyview mode: changes are disabled while viewing as another profile

webhooks

400webhooks.access_invalidwebhook role, payload mode, data profile, collections or tags are invalid
400webhooks.auth_invalidoutbound authorization must be bearer with a token or basic with a username and a password
403webhooks.collections_outside_keythis API key is limited to collections: list collection_ids of the webhook, all of them among the collections of the key
404webhooks.delivery_not_foundwebhook delivery not found
400webhooks.description_too_longwebhook description is longer than 200 characters
409webhooks.endpoint_disabledthe webhook is disabled; enable it first
409webhooks.event_not_permittedthe webhook would not receive this event now: its role, data profile, collections or tags no longer allow it, so the delivery is not repeated
400webhooks.events_requiredsubscribe to at least one event
403webhooks.feature_disabledwebhooks are not included in the organization's plan
400webhooks.headers_invalidcustom webhook headers are invalid: at most 10 headers, names of letters, digits and hyphens without reserved names, values up to 1024 bytes
400webhooks.invalid_urlwebhook url must be an absolute https address without credentials
404webhooks.not_foundwebhook not found
400webhooks.overlap_invalidrotation overlap must be between 0 and 168 hours
400webhooks.private_addresswebhook host resolves to a private or reserved network address
400webhooks.redeliver_invalidredelivery period must be within the last 30 days with since before until, and statuses must be success, exhausted or cancelled
409webhooks.too_manyan organization can have at most 20 webhooks
400webhooks.unknown_eventunknown webhook event {type}
400webhooks.unresolvablewebhook host does not resolve