Public preview
Best practices Public preview
Optimize batch job performance and handle errors effectively.
Use validation for critical operations
Keep skip_validation set to false (the default) for operations where partial processing would cause issues. Validation ensures your entire file is well-formed before any requests are executed.
Set skip_validation to true when you’ve already validated your input data and want faster job startup, or when processing partial results is acceptable.
Split large workloads
If you have an input file larger than 5GB, split workloads into multiple batch jobs. You can run multiple batch jobs concurrently.
Verify resource state before batching
Confirm that all target resources are in the required state before submitting a batch. For example, subscriptions must be active before they can be migrated with /v1/subscriptions/:id/migrate. Batch jobs execute the target operation directly and don’t change resource state as a prerequisite.
Handle errors in results
Always check the status field in each result line. Individual requests within a successful batch can still fail (for example, because of insufficient funds or invalid parameters). Build your integration to filter the results file for non- 200 statuses and handle failures accordingly.
Prepare your file before creating the job
The upload URL expires 5 minutes after batch job creation. Generate and validate your input file before calling the create endpoint. If you need to prepare data dynamically, complete all data retrieval and file generation first, then create the batch job and upload immediately.
Common errors
Upload URL expired
If you don’t upload the input file before the expires_at timestamp (5 minutes after job creation), the batch job transitions to upload_timeout status. Create a new batch job and upload the file promptly. Generate your input file before creating the batch job to avoid this.
Invalid resource state
Individual requests can fail if the target resource isn’t in the expected state. For example, when using /v1/subscriptions/:id/migrate:
- Subscription isn’t active : The subscription must be in an active state before you can migrate it. Canceled or incomplete subscriptions return a 400 error with resource _ invalid _ state .
- Subscription already migrated : Attempting to migrate a subscription that has already been migrated returns an error.
These per-request errors appear in the results file with a non- 200 status code. The batch job itself still completes successfully (the batch continues processing if individual lines fail).
Path parameter mismatches
The keys in path_params must exactly match the placeholders in the endpoint path. For example, if your endpoint path is /v1/subscriptions/:id/migrate, your path_params must use {"id": "sub_..."}. A mismatch between the placeholder name and the key causes a validation error or a 400 status in the results file.
Upload content type
The upload PUT request must use Content-Type: application/jsonlines. Other content types are rejected.
File format errors
These format errors are detected asynchronously after the upload, not at the PUT. A 200 response to the PUT doesn’t indicate the file will pass validation, so poll the job status to detect validation_failed.
When skip_validation is false, these errors cause the entire batch to fail with validation_failed status:
- Rows that aren’t valid JSON
- Missing id field on any row
- Duplicate id values across rows
- IDs containing characters outside A-Za-z0-9 _ -
When skip_validation is true, file-level format errors can cause individual rows to fail rather than blocking the entire batch.
Job processing timeout
Batch jobs that run longer than 7 days transition to timeout status. Partial results from requests that completed before the timeout are available in the results file.