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 with the same ID afterwards.

To index the document again once the task is published, use Re-index Documents. For the re-index flow, see Re-index and 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.

1 min read

post/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry

Request example

curl --request POST \
  --url https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry"
headers = {
    "Authorization": "Bearer <token>",
}

response = requests.request("POST", url, headers=headers)

print(response.text)

const response = await fetch('https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>'
  }
});

const data = await response.json();
console.log(data);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <token>',
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry"

	req, _ := http.NewRequest("POST", url, nil)
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry"))
    .header("Authorization", "Bearer <token>")
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

require 'uri'
require 'net/http'

url = URI('https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'

request = Net::HTTP::Post.new(url)
request['Authorization'] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

Response

{
  "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
}

{
  "code": "knowledge_fs_invalid_request",
  "message": "Agent Knowledge Base request is invalid.",
  "status": 400
}

{
  "code": "knowledge_fs_invalid_credential",
  "message": "Invalid Agent Knowledge Base service credential.",
  "status": 401
}

{
  "code": "unauthorized",
  "message": "Access token is invalid",
  "status": 401
}

{
  "code": "forbidden",
  "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.",
  "status": 403
}

{
  "code": "knowledge_fs_access_denied",
  "message": "Agent Knowledge Base operation is not allowed.",
  "status": 403
}

{
  "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
}

{
  "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
}

{
  "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
}

{
  "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
}

{
  "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
}

{
  "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
}

{
  "code": "knowledge_fs_upstream_unavailable",
  "message": "Agent Knowledge Base is unavailable.",
  "status": 502
}

{
  "code": "knowledge_fs_operation_unavailable",
  "message": "Agent Knowledge Base operation is not available.",
  "status": 503
}

{
  "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
}

post/knowledge-fs/spaces/{knowledge_base_id}/jobs/{task_id}/retry

Authorization

Authorizationstringheaderrequired#

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).

Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).

Path parameters

knowledge_base_idstringrequired#

Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's API Access dialog (…/knowledge-fs/spaces/<knowledge base ID>), and the segment after /datasets/new/ in the address bar.

task_idstringrequired#

Indexing task ID, the same in every place it appears: compilation_job.id of a queued item in the Re-index Documents response, latest_task.id from Get Document, id from List Document Indexing Tasks, and the id of a document task in List Background Tasks.

Responses

application/json

The restarted task. run_state is dispatch_pending, and error and completed_at are null.

base_head_revisioninteger#

Internal. Not needed to follow the task.

candidate_fingerprintstring#

Internal. Not needed to follow the task.

candidate_publication_idstring#

Internal. Not needed to follow the task.

completed_atnumber#

When the task reached a terminal stage, in epoch milliseconds. null while it runs and after a retry.

created_atnumber#

When the task was created, in epoch milliseconds.

document_asset_idstring#

ID of the document file being indexed. Usable with Get Document File. It is the asset.id of the Re-index Documents item that started the task, even when you submitted a document ID.

errorstring#

Short failure message. Can differ from failure.message. Set only when stage or run_state is failed. Otherwise null, including on canceled tasks.

execution_attemptsinteger#

Attempts made so far. Retry Indexing Task resets it to 0, so repeated retries never exhaust the attempt budget on their own.

failureobject#

Error details when the task failed. null otherwise.

Show child attributes

actionstring#

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.

categorystring#

Kind of failure: authorization, canceled, configuration, conflict, dependency, internal, not_found, rate_limit, timeout, or validation.

codestring#

Stable error code in upper snake case, for example KNOWLEDGE_FS_CONFLICT or SOURCE_CREDENTIAL_TEST_FAILED.

messagestring#

Public message for the error code or failure category. Provider error details are not exposed.

parametersobject#

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.

retryPolicystring#

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).

stagestring#

Stage the failure belongs to, for example query_generation or credential-test. null when not applicable; omitted from HTTP error bodies.

traceIdstring#

Reference to quote when contacting an administrator. May be null in a successful response containing failure details, or omitted from an HTTP error body.

idstring#

Indexing task ID.

knowledge_space_idstring#

Internal ID of the knowledge base. Not the knowledge base ID in the path.

max_execution_attemptsinteger#

Attempts allowed before the task fails.

run_statestring#

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 sets it to dispatch_pending.

stagestring#

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 keeps the checkpoint the attempt had reached, so the value is rarely queued after a retry.

updated_atnumber#

When the task last changed, in epoch milliseconds.

versioninteger#

Version of the document file being indexed.

Cancel Indexing Task Get Bulk Task