Queues
A queue is a named container for one-off HTTP jobs. Queues define shared configuration — timeout, retry strategy, success assertions, parallelism limits, and alerting — that applies to every job in the queue.
Why queues exist
Instead of configuring retries, timeouts, and assertions on every individual job, you configure them once on the queue. Every job pushed to that queue inherits these settings. This keeps your API calls simple (just specify the queue name, URL, and payload) while giving you full control over execution behavior.
Queue configuration
| Field | Type | Default | Description |
|---|---|---|---|
name | string | — | Unique name within your team |
is_active | boolean | true | Whether jobs in this queue are processed |
timeout_seconds | integer | 30 | HTTP request timeout (1-300 seconds) |
retries_enabled | boolean | true | Whether failed jobs are retried |
retry_delays | array | [60, 1800, 10800] | Seconds to wait before each retry attempt |
success_assertions | array | [] | Response conditions all jobs must satisfy |
alerts_enabled | boolean | false | Whether to send alerts on job failures |
max_parallelism | integer | unlimited | Maximum concurrent jobs processing at once |
dlq_retention_days | integer | 14 | Days to keep dead-lettered jobs before cleanup |
Auto-creation
When you push a job via the API with a queue name that does not exist, Recuro creates the queue automatically with default settings. You can then customize the queue from the dashboard.
Retry strategy
When retries_enabled is true, failed jobs are retried according to the retry_delays array. The default is:
| Attempt | Delay | Total elapsed |
|---|---|---|
| 1st retry | 60 seconds (1 min) | 1 min |
| 2nd retry | 1,800 seconds (30 min) | 31 min |
| 3rd retry | 10,800 seconds (3 hours) | 3 hrs 31 min |
Each retry creates a new job record linked to the original, with an incremented attempt_number. The original job is flagged with has_pending_retry: true until the retry chain resolves.
After all retries are exhausted, the job is moved to the dead-letter queue.
You can customize retry_delays to any array of up to 10 integer values (each between 1 and 86,400 seconds). The number of retry attempts equals the length of the array.
Parallelism
Set max_parallelism to limit how many jobs from this queue can be processing simultaneously. This is useful for rate-limited endpoints — if your target API allows 5 concurrent requests, set max_parallelism to 5.
When the parallelism limit is reached, additional ready jobs wait until a processing slot opens.
Success assertions
Queues can have the same success assertions as crons. Assertions defined on a queue apply to every job in that queue. If any assertion fails, the job is treated as failed and enters the retry flow.
Supported assertion types: status_code_equals, status_code_in, body_contains, body_not_contains, json_path_equals, response_time_under_ms.
Pausing a queue
Setting is_active to false pauses all job processing for that queue. Jobs already in-flight continue to completion, but no new jobs are dispatched. Pending jobs remain in the queue and are processed when the queue is reactivated.
If a job is dispatched while its queue is inactive, the job is marked as failed.
DLQ retention
Dead-lettered jobs are automatically cleaned up after dlq_retention_days (default: 14 days). You can set this to 3, 7, 14, or 30 days per queue. The cleanup runs daily.
Next steps
- Jobs — Understand the job lifecycle and retry chain
- Runs — What gets logged for each execution
- Schedule a Job (API) — Push jobs to a queue via the API
- Retry Strategy Design — Choosing retry counts and backoff