---
title: "Retry Failed Documents"
method: POST
path: "/v1/buckets/{bucket_identifier}/batches/{batch_id}/retry"
tags: ["Bucket Batches"]
---

# Retry Failed Documents

`POST /v1/buckets/{bucket_identifier}/batches/{batch_id}/retry`

## Request

- Base URL: `https://api.mixpeek.com`
- URL: `https://api.mixpeek.com/v1/buckets/{bucket_identifier}/batches/{batch_id}/retry`
- Auth: HTTP bearer and API key in header `X-Namespace`

Retry failed documents in a batch with intelligent filtering by error type and tier.

## Path parameters

- `bucket_identifier` string, required: The unique identifier of the bucket.
- `batch_id` string, required: The unique identifier of the batch.

## Request body

- RetryBatchRequest: 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` 'transient_only' | 'all': 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.
  - `tier_nums` integer[], nullable: 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.
  - `max_retry_count` integer: 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.

## Response `200`

Successful Response

- object

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `429`: Too Many Requests
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-09** `61a175e8eb9a`: 1 warning, 5 info
  - removed the optional property `detail` from the response with the `422` status
  - added the non-success response with the status `429`
  - added the non-success response with the status `503`
  - added the optional property `success` to the response with the `422` status
  - …2 more
- **2026-08-09** `5d4c905106b4`: 1 info
  - the endpoint scheme security `BearerAuth AND NamespaceHeader` was added to the API

[Operation history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/buckets/:bucket_identifier/batches/:batch_id/retry/post.md)

---

[API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) - [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mixpeek/apis/mixpeek-api/revisions/790bc16455f6?raw)