Skip to content
Survey Coder Pro Survey Coder Pro

CODEBOOK_GENERATION_FAILED — Codebook step failed

Summary

Section titled “Summary”

Stage 2 of the pipeline — codebook generation — failed. This is usually transient (an LLM hiccup) but occasionally signals the response set is too sparse or noisy for the model to extract a useful taxonomy.

HTTP status

Section titled “HTTP status”

500 Internal Server Error. Standard envelope.

Example response

Section titled “Example response”
{
  "success": false,
  "error": {
    "code": "CODEBOOK_GENERATION_FAILED",
    "message": "Codebook generation failed after 3 retries. The response set may be too small or too noisy.",
    "request_id": "req_01HXJZK4ABCDEF",
    "doc_url": "https://docs.surveycoder.io/errors/codebook-generation-failed"
  }
}

Why this happens

Section titled “Why this happens”
  • An upstream LLM provider had a transient failure.
  • The response set is too small (< 5 distinct verbatims) — the model has nothing to generalize from.
  • The responses are mostly junk ("asdf", "-", "x") and got filtered out, leaving too few to work with.
  • The question text is ambiguous and the model can’t decide on a taxonomy.

How to fix it

Section titled “How to fix it”

  1. Retry once. Most of these are transient.

  2. Give the model more data. Aim for at least 30-50 verbatims for codebook generation.

  3. Pre-filter junk. Heavy noise removal is your responsibility; the API only does a minimal clean.

  4. Pass an explicit codebook with the request and skip generation entirely:

    POST /v1/code
    { "question": "...", "codebook": [/* your taxonomy */], "responses": [...] }

  5. Sharpen the question text. “Tell us more” yields worse codebooks than “Which brand of laundry detergent do you prefer and why?”

Section titled “Related”