Build reliable workers

Own the whole job lifecycle

1. Activate with POST /api/v1/jobs/activate and always send type: without it, jobs of every type are handed out. The call answers at once, with "jobs": [] when nothing waits, so sleep 1 to 5 seconds before the next poll.
2. Validate the input before calling an external service. Record a stable business key for any side effect.
3. Complete with POST /api/v1/jobs/{key}/complete only after the work succeeds. It answers 204 with an empty body.
4. On failure, call POST /api/v1/jobs/{key}/fail with {"retries", "errorMessage"}. retries is the count the server stores, not a decrement: send job.retries - 1 to use one attempt. Zero, or no retries at all, raises an incident at once.

Handle empty success responses

async function readResponse(response) {
  const text = await response.text();
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${text}`);
  }
  return text ? JSON.parse(text) : null;
}

Activate answers 200, complete and fail answer 204 with no body. Treat any 2xx as success. A 404 on complete or fail after a retry means the job is gone, most likely already applied: read the instance to reconcile rather than repeating the side effect. Keep credentials on the server that runs this helper.

Jobs do not expire

An activated job stays with the worker that took it until that worker completes or fails it. The server never hands it to another worker and never times it out; the deadline field is informational. A worker that exits while holding jobs strands them until the server restarts, so on shutdown stop activating, wait for the jobs in flight, and fail every unfinished job with retries equal to job.retries, which puts it back in the queue without using an attempt.

To bound work in time, model a timer boundary event. Make external side effects idempotent on the job key, so that a successful action followed by a lost completion cannot charge or notify twice.

The activation request

curl -sX POST https://priostack.com/api/v1/jobs/activate \
  -H "X-API-Key: $PRIOSTACK_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"type":"send-email","maxJobsToActivate":10}'
# 200 {"jobs":[...]} at once; {"jobs":[]} when nothing waits

The server reads type (jobType is accepted as an alias) and maxJobsToActivate, which has no default and no ceiling. worker and timeout are accepted and ignored, and any other field has no effect. Job keys are strings.