Batch Job Design
Patterns for long-running operations — progress tracking, idempotency keys, and graceful failure recovery in Meridian workflows.
Idempotency Keys
Every batch job accepts a client-generated idempotency key. If the same key arrives twice, Meridian returns the original result without re-executing. Use UUID v4 and store keys for at least 24 hours.
POST /v1/jobs
{
"idempotency_key": "a1b2c3d4-...",
"recipe": "export_users",
"payload": { "org_id": "org_01" }
}Progress & Polling
Jobs report progress as a float between 0 and 1. Poll the status endpoint with exponential backoff — start at 1s, cap at 30s. Completed jobs include a signed result URL valid for 1 hour.
GET /v1/jobs/job_7xKp2m
→ { "status": "processing", "progress": 0.62 }Failure Recovery
Jobs that fail with a retryable error are automatically requeued up to 3 times with jitter. Non-retryable failures (validation, auth) return immediately. Always inspect the error_code field before retrying client-side.
Webhooks
Instead of polling, register a webhook URL. Meridian sends a signed POST when the job reaches a terminal state. Validate the X-Meridian-Signature header with your shared secret.
Next step: Webhook signatures & verification