JOB_ALREADY_RUNNING — A job is already in flight

Summary

You tried to start a job (codebook generation, coding, or refinement) but another job of the same type is already running for this question. We serialize per-question to keep state consistent.

HTTP status

409 Conflict. Standard envelope.

Example response

{
  "success": false,
  "error": {
    "code": "JOB_ALREADY_RUNNING",
    "message": "A codebook job (job_01HXJZK...) is already running for question q_01HXJZK....",
    "request_id": "req_01HXJZK4ABCDEF",
    "doc_url": "https://docs.surveycoder.io/errors/job-already-running"
  }
}

Why this happens

• A previous async job hasn’t finished.
• A retry fired before the first request was queued (rare).
• Two clients (e.g. dashboard + CI) kicked off jobs simultaneously.

How to fix it

1. The error includes the running job_id. Poll GET /v1/jobs/{id} until it ends.
2. Or skip polling and set up a webhook — job.completed fires automatically.
3. If the running job has been processing for over 30 minutes with no progress, it may be stuck. Cancel it with DELETE /v1/jobs/{id} and retry.
4. Use idempotency keys so your own retries don’t trigger this.

Related

• ALREADY_CODING — the coding-specific form
• Coding pipeline