---
title: "Get batch inventory errors"
method: GET
path: "/availability/v1/inventory/batch/{batchId}/errors"
tags: ["Batch operations"]
---

# Get batch inventory errors

`GET /availability/v1/inventory/batch/{batchId}/errors`

Returns a pre-signed URL to download a CSV file containing all rows that failed processing, along with error codes and messages. The error reports are available until the batch metadata expires (7 days after batch completion).

>ℹ️ This feature is in early access, which means that we are working to improve it. If you want to use this feature, please contact our [Support Center](https://support.vtex.com/hc/en-us/requests).

This endpoint is part of the Batch operations section for high-throughput [inventory updates](https://help.vtex.com/en/docs/tutorials/updating-the-quantity-of-items-in-inventory). Learn more about [inventory management at VTEX](https://help.vtex.com/en/docs/tutorials/managing-stock-items).

## Endpoint Availability

The Get batch inventory errors endpoint is available when:
- `errorCount > 0` in the status response
- [Status](https://developers.vtex.com/docs/api-reference/logistics-api#get-/availability/v1/inventory/batch/-batchId-/status) is one of: `PROCESSING`, `COMPLETED`, `COMPLETED_WITH_ERRORS`, or `FAILED`

If these conditions are not met, the endpoint response will be `204 No Content`.

## Error Types

**Deterministic Errors**: Errors caused by invalid or incomplete data in the submitted file, for example a missing required fields or invalid values. These errors are detected during the file ingestion from S3 and will cause the affected records to fail. The system doesn't retry these operations automatically. The user must fix the data in the CSV file and resubmit a new batch.

**Non-Deterministic Errors**: Errors caused by infrastructure or system issues. The system will automatically retry the operation up to 3 times. If the operation still fails after these attempts, the message will be sent to a Dead Letter Queue (DLQ) for further investigation. These errors will show `UPDATE_FAILED` in the error CSV.

## Error CSV Schema

The downloaded CSV file contains the following fields:

| **Field** | **Type** | **Description** |
| --------------- | ----------------- | ----------------- |
| `line_number` | integer | Original line number in the uploaded CSV. |
| `item_id` | string | SKU identifier from the failed row. |
| `container_id` | string | Warehouse ID from the failed row. |
| `error_code` | string | Machine-readable error code. |
| `error_message` | string | Human-readable error description. |

## Error Codes

- `INVALID_QUANTITY`: Quantity value is invalid (negative, non-numeric)
- `MISSING_REQUIRED_FIELD`: Required field is empty or missing
- `INVALID_DATE_FORMAT`: Date/time field has invalid format
- `UPDATE_FAILED`: Database update failed after retries (non-deterministic error)
- `INSERT_CONFLICT`: Insert conflicted with a concurrent operation
- `INVALID_FORMAT`: Row format is invalid (e.g., wrong number of columns)
- `CONFLICT`: Compare-And-Set conflict or per-item routing conflict
- `UNKNOWN`: Unclassified error

## Error CSV Example

```csv
line_number,item_id,container_id,error_code,error_message
1523,SKU-12345,WH-01,INVALID_QUANTITY,"quantity cannot be negative: -50"
4892,SKU-67890,WH-01,MISSING_REQUIRED_FIELD,"container_id is required"
10234,SKU-11111,WH-01,INVALID_DATE_FORMAT,"supply_date is not valid"
```

## Permissions

Any user or [API key](https://developers.vtex.com/docs/guides/authentication-overview#api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a status code `403` error. These are the applicable resources for this endpoint:

| **Product** | **Category** | **Resource** |
| --------------- | ----------------- | ----------------- |
| Logistics | Logistics access | **Logistics - Full access** |

You can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):

| **Role** | **Resource** |
| --------------- | ----------------- |
| Logistics - Full access | Logistics - Full access |
| OMS - Full access | Logistics - Full access |

>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or API keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm).

To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication-overview#machine-authentication).

## Path parameters

- `batchId` string, uuid, required

## Headers

- `Accept` string, required

## Response `200`

OK

Error report available for download.

- object
  - `batchId` string, uuid, required — Unique identifier for the batch job.
  - `downloadUrl` string, uri, required — Pre-signed URL to download the error CSV (valid for 60 minutes).
  - `errorCount` integer, required — Total number of rows with errors.

## Other responses

- `204` — No Content No errors or report not available.
- `400` — Bad Request Invalid batch ID format.
- `401` — Unauthorized Missing or invalid authentication.
- `403` — Forbidden Insufficient permissions.
- `404` — Not Found Batch not found.
- `500` — Internal Server Error Unexpected error occurred while retrieving the error report.

## Changes

- **2026-05-07** `e5c20feff4af` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/vtex/apis/logistics-api/changes/availability/v1/inventory/batch/:batchId/errors/get.md)

---

[API](https://skmtc.dev/vtex/apis/logistics-api.md) · [All operations](https://skmtc.dev/vtex/apis/logistics-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/vtex/logistics-api/revisions/b8c8c6ef0b8a/schema)