Get batch inventory 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.

This endpoint is part of the Batch operations section for high-throughput inventory updates. Learn more about inventory management at VTEX.

Endpoint Availability

The Get batch inventory errors endpoint is available when:

• errorCount > 0 in the status response
• 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:

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

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 must have at least one of the appropriate License Manager resources 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:

You can create a custom role with that resource or use one of the following predefined roles:

❗ Assigning a predefined role to users or API keys usually grants permission to multiple License Manager resources. 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.

To learn more about machine authentication at VTEX, see Authentication overview.