Error reference

Every error response from the Survey Coder Pro API follows the same shape:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'responses' must be a non-empty array.",
    "request_id": "req_01HXJZK4ABCDEF",
    "doc_url": "https://docs.surveycoder.io/errors/validation-error"
  }
}

Every code below has a dedicated page with the typical HTTP status, why it happens, and how to fix it. If you’re debugging a live request, follow the doc_url straight from the JSON.

By category

Auth (401, 403, 429)

Code	Status	Summary
UNAUTHORIZED	401	No API key, invalid key, or wrong header name.
AUTH_ERROR	401	Generic auth failure — couldn’t resolve org from key.
KEY_REVOKED	401	The key was active but has been revoked.
KEY_EXPIRED	401	The key is past its expiry timestamp.
INSUFFICIENT_SCOPE	403	Key is valid but missing required scope.
RATE_LIMITED	429	Over per-key requests-per-minute limit.
NO_ORG	401	Key valid but no organization found.

Credits (402)

Code	Status	Summary
INSUFFICIENT_CREDITS	402	Balance is at or below zero.
TRIAL_LIMIT_EXCEEDED	402	Free trial has been used up.
NEGATIVE_BALANCE	402	Negative-allowed plan hit its floor.

Validation (404, 409, 422)

Code	Status	Summary
VALIDATION_ERROR	422	Body shape or types are wrong.
NOT_FOUND	404	Resource doesn’t exist or isn’t in your org.
ALREADY_CODING	409	Question is already mid-coding.
INVALID_STATE	409	Resource is in a state that can’t accept this op.
EMPTY_CODEBOOK	422	Trying to code/clone from a question with no codebook.
NO_DATA	422	Trying to operate on a question with no responses.
NOT_GROUPED	409	Op requires question grouping; none exists.
JOB_ALREADY_RUNNING	409	A coding or codebook job is already running.

Processing (500, 504)

Code	Status	Summary
CODEBOOK_GENERATION_FAILED	500	LLM failed to generate a codebook.
CODING_FAILED	500	Pipeline failed mid-run.
INTERNAL_ERROR	500	Unhandled server error.
GATEWAY_TIMEOUT	504	Upstream call timed out.
CONFIG_ERROR	500	Server is missing required config.
DB_ERROR	500	Database query failure.

External (502, 503)

Code	Status	Summary
SPSS_SERVICE_ERROR	503	SPSS microservice degraded (.sav export only).
SERVICE_UNAVAILABLE	503	A dependency is down. Retry.
QUEUE_UNAVAILABLE	503	Redis or BullMQ unavailable. Async jobs can’t queue.

Always check request_id

Every error response includes a request_id (e.g. req_01HXJZK4ABCDEF). Quote it in any support email — we use it to find your specific request in the logs in seconds.

Need help? Email support@surveycoder.io with the request_id from your error.