> ## Documentation Index > Fetch the complete documentation index at: https://docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # Retry Indexing Task > Restarts an indexing task whose `run_state` is `failed` or `canceled` under the same task ID and returns the updated task. Poll [Get Indexing Task](/en/api-reference/indexing-tasks/get-indexing-task) with the same ID afterwards. To index the document again once the task is `published`, use [Re-index Documents](/en/api-reference/documents-and-chunks/re-index-documents). For the re-index flow, see [Re-index and Track Indexing](/en/api-reference/guides/knowledge-base#track-indexing). An attempt with `run_state: superseded` cannot be retried, even though its `stage` is `canceled`. If you saved a newer task ID from a re-index response, poll that task. ## OpenAPI ````yaml /en/api-reference/openapi_service.json post /knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry openapi: 3.0.1 info: description: >- REST API for Dify applications and knowledge bases. Application endpoints authenticate with an app API key; knowledge endpoints authenticate with a dataset API key. title: Dify Service API version: 1.0.0 servers: - description: >- Base URL of the Dify Service API. For self-hosted deployments, replace it with your own API base URL. url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: Host and path of the API base URL, without the `https://` prefix. security: - ApiKeyAuth: [] tags: - description: Operations related to chat messages and interactions. name: Chat Messages - description: File upload and preview operations. name: Files - description: Operations related to end user information. name: End Users - description: User feedback operations. name: Feedback - description: Operations related to managing conversations. name: Conversations - description: Text-to-Speech and Speech-to-Text operations. name: Audio - description: Operations to retrieve application settings and information. name: Applications - description: Operations related to managing annotations for direct replies. name: Annotations - description: Endpoints for resuming paused workflows that require human input. name: Human Input - description: Operations for executing and managing workflows. name: Workflow Runs - description: Operations related to text generation and completion. name: Completion Messages - description: >- Operations for managing knowledge bases, including creation, configuration, and retrieval. name: Knowledge Bases - description: >- Operations for creating, updating, and managing documents within a knowledge base. name: Documents - description: Operations for managing document chunks and child chunks. name: Chunks - description: >- Operations for managing knowledge base metadata fields and document metadata values. name: Metadata - description: Operations for managing knowledge base tags and tag bindings. name: Tags - description: Operations for retrieving available models. name: Models - description: >- Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution. name: Knowledge Pipeline - description: Ask a knowledge base a question and stream the answer. name: Queries - description: Inspect what a query retrieved and why. name: Query Records - description: Run a research question in the background and collect its results. name: Research Tasks - description: >- Read the documents in a knowledge base, their files, revisions, and chunks; label documents with metadata. name: Documents and Chunks - description: >- Follow, cancel, or retry indexing, and list the knowledge base's background tasks. name: Indexing Tasks - description: >- Follow the deletion of a document file, a batch of files, or a source until it finishes. name: Deletion Jobs - description: >- Manage the sources that feed a knowledge base, their sync schedules, and their connections. name: Sources - description: >- Sync a source now, import website pages or provider items, and follow, cancel, or retry the runs. name: Source Syncs and Imports - description: >- Read and change the knowledge base's models and retrieval settings, and follow the migration a change starts. name: Settings paths: /knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry: post: tags: - Indexing Tasks summary: Retry Indexing Task description: >- Restarts an indexing task whose `run_state` is `failed` or `canceled` under the same task ID and returns the updated task. Poll [Get Indexing Task](/en/api-reference/indexing-tasks/get-indexing-task) with the same ID afterwards. To index the document again once the task is `published`, use [Re-index Documents](/en/api-reference/documents-and-chunks/re-index-documents). For the re-index flow, see [Re-index and Track Indexing](/en/api-reference/guides/knowledge-base#track-indexing). An attempt with `run_state: superseded` cannot be retried, even though its `stage` is `canceled`. If you saved a newer task ID from a re-index response, poll that task. operationId: retryIndexingTask parameters: - description: >- Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's **API Access** dialog (`…/knowledge-fs/spaces/`), and the segment after `/datasets/new/` in the address bar. in: path name: knowledge_base_id required: true schema: format: uuid type: string - description: >- Indexing task ID, the same in every place it appears: `compilation_job.id` of a `queued` item in the [Re-index Documents](/en/api-reference/documents-and-chunks/re-index-documents) response, `latest_task.id` from [Get Document](/en/api-reference/documents-and-chunks/get-document), `id` from [List Document Indexing Tasks](/en/api-reference/indexing-tasks/list-document-indexing-tasks), and the `id` of a `document` task in [List Background Tasks](/en/api-reference/indexing-tasks/list-background-tasks). in: path name: task_id required: true schema: format: uuid type: string responses: '200': content: application/json: examples: success: summary: Response Example value: base_head_revision: 1 candidate_fingerprint: null candidate_publication_id: null completed_at: null created_at: 1788681600000 document_asset_id: 6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b error: null execution_attempts: 0 failure: null id: e4a1f0b2-7c3d-4e5f-9a1b-2c3d4e5f6a7b knowledge_space_id: 9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b max_execution_attempts: 3 run_state: dispatch_pending stage: outline_built updated_at: 1788681800000 version: 1 schema: $ref: '#/components/schemas/KnowledgeBaseIndexingTask' description: >- The restarted task. `run_state` is `dispatch_pending`, and `error` and `completed_at` are `null`. '400': content: application/json: examples: knowledge_fs_invalid_request_path: summary: knowledge_fs_invalid_request (path ID) value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 description: '- `knowledge_fs_invalid_request`: `task_id` is malformed.' '401': content: application/json: examples: knowledge_fs_invalid_credential: summary: knowledge_fs_invalid_credential value: code: knowledge_fs_invalid_credential message: Invalid Agent Knowledge Base service credential. status: 401 unauthorized: summary: unauthorized value: code: unauthorized message: Access token is invalid status: 401 description: >- - `unauthorized`: the `Authorization` header is missing, or the key is unknown or not a knowledge base API key. - `knowledge_fs_invalid_credential`: the key is valid, but no knowledge base with this ID exists in the key's workspace, or the key is not tied to a workspace. '403': content: application/json: examples: forbidden: summary: forbidden (rate limit) value: code: forbidden message: >- Sorry, you have reached the knowledge base request rate limit of your subscription. status: 403 knowledge_fs_access_denied: summary: knowledge_fs_access_denied (key scope) value: code: knowledge_fs_access_denied message: Agent Knowledge Base operation is not allowed. status: 403 knowledge_fs_access_denied_2: summary: knowledge_fs_access_denied (upstream) value: code: knowledge_fs_access_denied failure: action: contact_admin category: authorization code: KNOWLEDGE_FS_ACCESS_DENIED message: >- You do not have permission to perform this Agent Knowledge Base operation. retryPolicy: never traceId: 8f3a2c14-9d6b-4c07-b5a1-2e7d0c93f5b2 message: >- You do not have permission to perform this Agent Knowledge Base operation. status: 403 description: >- - `knowledge_fs_access_denied`: the key is scoped to other knowledge bases, **API access** is off for this knowledge base, or the knowledge base is not active. - `knowledge_fs_access_denied`: the key has no access to this knowledge base's content, or the key lost write access to this knowledge base. - `forbidden`: on Dify Cloud, the workspace has reached the knowledge base request rate limit of its subscription. Every call counts, reads included. '404': content: application/json: examples: knowledge_fs_resource_not_found: summary: knowledge_fs_resource_not_found value: code: knowledge_fs_resource_not_found failure: category: not_found code: KNOWLEDGE_FS_NOT_FOUND message: >- The requested Agent Knowledge Base resource was not found. retryPolicy: never traceId: 8f3a2c14-9d6b-4c07-b5a1-2e7d0c93f5b2 message: The requested Agent Knowledge Base resource was not found. status: 404 not_found: summary: not_found (feature off) value: code: not_found message: >- The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again. status: 404 description: >- - `knowledge_fs_resource_not_found`: no indexing task has this ID, or the document file it indexes is no longer readable with this key. - `not_found`: the Agent Knowledge Base feature is turned off on this deployment. '409': content: application/json: examples: document_compilation_profile_changed: summary: knowledge_fs_conflict (model configuration changed) value: code: knowledge_fs_conflict failure: action: configure_model category: configuration code: DOCUMENT_COMPILATION_PROFILE_CHANGED message: >- The model configuration changed or is unavailable. Check the knowledge space models before retrying document processing. retryPolicy: after_configuration traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- The model configuration changed or is unavailable. Check the knowledge space models before retrying document processing. status: 409 knowledge_fs_conflict: summary: knowledge_fs_conflict value: code: knowledge_fs_conflict failure: action: retry category: conflict code: KNOWLEDGE_FS_CONFLICT message: >- The Agent Knowledge Base operation conflicts with the current resource state. retryPolicy: manual traceId: 8f3a2c14-9d6b-4c07-b5a1-2e7d0c93f5b2 message: >- The Agent Knowledge Base operation conflicts with the current resource state. status: 409 description: >- - `knowledge_fs_conflict`: the task is not in `failed` or `canceled`, or another attempt for the same file is already running. - `knowledge_fs_conflict`: the knowledge base's model configuration changed or is unavailable. `failure.code` is `DOCUMENT_COMPILATION_PROFILE_CHANGED`, with `action` `configure_model`. Check the models in [Get Knowledge Base Settings](/en/api-reference/settings/get-knowledge-base-settings) before retrying. '413': content: application/json: examples: knowledge_fs_request_too_large: summary: knowledge_fs_request_too_large (vector storage limit) value: code: knowledge_fs_request_too_large failure: action: retry category: configuration code: VECTOR_SPACE_QUOTA_EXCEEDED message: >- The workspace vector storage limit has been reached. Delete documents or upgrade the plan before indexing more. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- The workspace vector storage limit has been reached. Delete documents or upgrade the plan before indexing more. status: 413 description: >- - `knowledge_fs_request_too_large`: the workspace's vector storage limit has been reached. `failure.code` is `VECTOR_SPACE_QUOTA_EXCEEDED`. Delete documents or upgrade the plan before retrying. '502': content: application/json: examples: knowledge_fs_upstream_unavailable: summary: knowledge_fs_upstream_unavailable value: code: knowledge_fs_upstream_unavailable message: Agent Knowledge Base is unavailable. status: 502 description: >- - `knowledge_fs_upstream_unavailable`: no answer came back in time, or the answer couldn't be read. The retry may have taken effect. Read [Get Indexing Task](/en/api-reference/indexing-tasks/get-indexing-task) with the same task ID before deciding whether to retry. Check its `stage` and `run_state` against this operation's requirements; repeating the action can be rejected after the task changes state. '503': content: application/json: examples: knowledge_fs_operation_unavailable: summary: knowledge_fs_operation_unavailable value: code: knowledge_fs_operation_unavailable message: Agent Knowledge Base operation is not available. status: 503 knowledge_fs_operation_unavailable_upstream: summary: knowledge_fs_operation_unavailable (temporary) value: code: knowledge_fs_operation_unavailable failure: action: retry category: dependency code: KNOWLEDGE_FS_UNAVAILABLE message: >- A service required by Agent Knowledge Base is temporarily unavailable. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- A service required by Agent Knowledge Base is temporarily unavailable. status: 503 description: >- - `knowledge_fs_operation_unavailable`: the Agent Knowledge Base feature is not set up for this workspace, this operation is not available on the deployment, or the key's access to this knowledge base changed while the request was being authorized. - `knowledge_fs_operation_unavailable`: the request can't be served right now. Follow `failure.retryPolicy`. components: schemas: KnowledgeBaseIndexingTask: properties: base_head_revision: description: Internal. Not needed to follow the task. nullable: true type: integer candidate_fingerprint: description: Internal. Not needed to follow the task. nullable: true type: string candidate_publication_id: description: Internal. Not needed to follow the task. nullable: true type: string completed_at: description: >- When the task reached a terminal stage, in epoch milliseconds. `null` while it runs and after a retry. nullable: true type: number created_at: description: When the task was created, in epoch milliseconds. type: number document_asset_id: description: >- ID of the document file being indexed. Usable with [Get Document File](/en/api-reference/documents-and-chunks/get-document-file). It is the `asset.id` of the [Re-index Documents](/en/api-reference/documents-and-chunks/re-index-documents) item that started the task, even when you submitted a document ID. type: string error: description: >- Short failure message. Can differ from `failure.message`. Set only when `stage` or `run_state` is `failed`. Otherwise `null`, including on canceled tasks. nullable: true type: string execution_attempts: description: >- Attempts made so far. [Retry Indexing Task](/en/api-reference/indexing-tasks/retry-indexing-task) resets it to `0`, so repeated retries never exhaust the attempt budget on their own. nullable: true type: integer failure: allOf: - $ref: '#/components/schemas/KnowledgeBaseErrorDetails' description: Error details when the task failed. `null` otherwise. nullable: true id: description: Indexing task ID. type: string knowledge_space_id: description: >- Internal ID of the knowledge base. Not the knowledge base ID in the path. type: string max_execution_attempts: description: Attempts allowed before the task fails. nullable: true type: integer run_state: description: >- Scheduler state of the current attempt: - `dispatch_pending`: accepted, waiting to be dispatched to a worker. - `queued`: dispatched, waiting for a worker. - `running`: a worker is executing the task. - `retry_wait`: an automatic retry is scheduled, and `stage` stays unchanged. - `succeeded`: accompanies `stage: published`. - `failed`, `canceled`: terminal. - `superseded`: a newer attempt replaced this one. Terminal, reported with `stage: canceled`, and accepted by neither cancel nor retry. `null` when not set. [Retry Indexing Task](/en/api-reference/indexing-tasks/retry-indexing-task) sets it to `dispatch_pending`. nullable: true type: string stage: description: >- Indexing stage, in forward order: - `queued` - `parsed` - `outline_built` - `nodes_generated` - `projection_built` - `smoke_eval_passed` - `published` `published` means the new revision is active. `failed` and `canceled` are the other terminal values. [Retry Indexing Task](/en/api-reference/indexing-tasks/retry-indexing-task) keeps the checkpoint the attempt had reached, so the value is rarely `queued` after a retry. type: string updated_at: description: When the task last changed, in epoch milliseconds. type: number version: description: Version of the document file being indexed. type: integer type: object KnowledgeBaseErrorDetails: properties: action: description: >- Suggested next step, when there is one: `configure_model`, `configure_parser`, `configure_source`, `contact_admin`, `reupload`, or `retry`. `null` when not applicable; omitted from HTTP error bodies. nullable: true type: string category: description: >- Kind of failure: `authorization`, `canceled`, `configuration`, `conflict`, `dependency`, `internal`, `not_found`, `rate_limit`, `timeout`, or `validation`. type: string code: description: >- Stable error code in upper snake case, for example `KNOWLEDGE_FS_CONFLICT` or `SOURCE_CREDENTIAL_TEST_FAILED`. type: string message: description: >- Public message for the error code or failure category. Provider error details are not exposed. type: string parameters: additionalProperties: true description: >- Up to 8 values that qualify the failure, with keys among `attempt`, `currentRowVersion`, `documentCount`, `expectedRowVersion`, `fileSizeBytes`, `limit`, `maxFileSizeBytes`, `maxItems`, `modelType`, `providerKind`, `retryAfterSeconds`, and `status`. `null` when there are none; omitted from HTTP error bodies. nullable: true type: object retryPolicy: description: >- Whether a retry can help: `automatic` (the service retries on its own), `manual` (retry yourself), `after_configuration` (fix the knowledge base's setup in Dify first), or `never` (change the request). type: string stage: description: >- Stage the failure belongs to, for example `query_generation` or `credential-test`. `null` when not applicable; omitted from HTTP error bodies. nullable: true type: string traceId: description: >- Reference to quote when contacting an administrator. May be `null` in a successful response containing failure details, or omitted from an HTTP error body. nullable: true type: string type: object securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- Every request authenticates with an API key: `Authorization: Bearer {API_KEY}`. App endpoints take an app API key; knowledge endpoints take a knowledge base API key ([Get Started](/en/api-reference/guides/get-started)). Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP `401` (`unauthorized`). scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.