Skip to main content
POST
/
v1
/
buckets
/
{bucket_identifier}
/
batches
/
{batch_id}
/
retry
Retry Failed Documents
curl --request POST \
  --url https://api.mixpeek.com/v1/buckets/{bucket_identifier}/batches/{batch_id}/retry \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '{
  "description": "Retry only transient errors (default, recommended)",
  "retry_mode": "transient_only"
}'
{}

Authorizations

​
Authorization
string
header
required

Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.

Headers

​
Authorization
string
required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer sk_live_abc123def456"

"Bearer sk_test_xyz789"

​
X-Namespace
string
required

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Examples:

"ns_abc123def456"

"production"

"my-namespace"

Path Parameters

​
bucket_identifier
string
required

The unique identifier of the bucket.

​
batch_id
string
required

The unique identifier of the batch.

Body

application/json

Request to retry failed documents in a batch.

Allows selective retry of failed documents with intelligent filtering by error type and tier. Retries use exponential backoff and respect max retry limits.

Use Cases: - Retry only transient errors after resolving temporary infrastructure issues - Retry specific processing tiers that failed - Retry all failed documents regardless of error type (force retry)

Requirements: - retry_mode: REQUIRED. Determines which documents to retry - tier_nums: OPTIONAL. Only retry failures from specific tiers (empty = all tiers) - max_retry_count: OPTIONAL. Skip documents that have been retried this many times

Behavior: - 'transient_only': Retries only transient errors (network, timeout, rate limit) - 'all': Retries both transient and permanent errors - Documents beyond max_retry_count are excluded from retry - Each retry increments the document's retry_count

​
retry_mode
enum<string>
default:transient_only

Determines which types of failed documents to retry. 'transient_only': Only retry documents that failed with transient errors (network issues, timeouts, rate limits). This is the recommended default as it avoids retrying documents with permanent failures (invalid data, missing fields, incompatible formats). 'all': Retry all failed documents regardless of error type. Use this for force retries after fixing data issues or updating extraction logic.

Available options:
transient_only,
all
Examples:

"transient_only"

"all"

​
tier_nums
integer[] | null

List of specific tier numbers to retry failures from. OPTIONAL - If not provided or empty list, retries failures from all tiers. Use this to selectively retry a specific processing stage. Example: [2] would only retry failures from tier 2 (the third processing stage). Tier numbering starts at 0 (bucket → collection), tier 1+ are collection → collection.

Examples:
[2]
[1, 2]

null

​
max_retry_count
integer
default:3

Maximum number of times a document can be retried. Documents that have been retried this many times already are excluded. Prevents infinite retry loops for documents with persistent issues. Default is 3 retries per document. Set to higher value for more aggressive retries.

Required range: 1 <= x <= 10
Examples:

3

5

1

Response

Successful Response

The response is of type object.