Errors and launch validation

Study API errors use a machine-readable code and a human-readable message. Validation failures can also include an errors array with precise paths and issue codes.

{
  "code": "INVALID_STUDY",
  "message": "The Study failed validation.",
  "errors": [
    {
      "code": "DUPLICATE_QUESTION_NAME",
      "path": "body/name",
      "message": "Question names must be unique within a Study."
    }
  ]
}

Use code for program logic. Display message for operators, and log the complete response after removing credentials and respondent data.

Validate before launch

Call POST /v2/studies/{studyId}/validate before changing the Study status to IN_PROGRESS. Validation is read-only and does not require If-Match.

{
  "status": "DRAFT",
  "errors": [
    {
      "code": "TARGETING_REQUIRED",
      "path": "targeting/triggers",
      "message": "At least one Event trigger is required."
    }
  ]
}

An empty errors array means the current definition is ready to launch. A successful validation does not reserve the Study version, so launch with the latest ETag. Launch validation issue codes are:

Code	Meaning
`QUESTION_REQUIRED`	The Study needs at least one supported Question.
`INVALID_CONSENT_DOCUMENT`	A consent document is missing or invalid.
`TARGETING_REQUIRED`	An in-product survey needs at least one Event trigger.
`OPTION_IMAGES_MISSING`	An image-based Question has incomplete Option images.
`OPTION_LABELS_MISSING`	A Question has incomplete Option labels.
`STUDY_FEATURE_DISABLED`	The Study uses a feature unavailable to the account.

If a launch request fails with 422 STUDY_NOT_READY, its errors array uses the same issue format.

Common response codes

Status	Code	Meaning and recovery
`400`	`INVALID_VALUE`, `INVALID_STUDY_ASSET`, or request validation code	Correct the header, body, query, path parameter, media type, or upload.
`403`	—	Add or correct the environment API key, and check account availability.
`404`	`STUDY_NOT_FOUND`, `QUESTION_NOT_FOUND`, `BLOCK_NOT_FOUND`, `ASSET_NOT_FOUND`, `TRANSLATION_NOT_FOUND`, or `TRANSLATION_JOB_NOT_FOUND`	Verify that the ID belongs to the authenticated environment.
`409`	`INVALID_STUDY_STATUS`	Make the change while the Study is editable.
`409`	`UNSUPPORTED_TARGETING`, `UNSUPPORTED_STUDY_DEFINITION`, `UNSUPPORTED_STUDY_SETTINGS`, or `UNSUPPORTED_TRANSLATION_DEFINITION`	The stored legacy definition cannot be represented safely by this API. Read it in Sprig or contact Support before overwriting it.
`409`	`QUESTION_IN_USE`, `OPTION_IN_USE`, or `ASSET_IN_USE`	Remove or update surviving references before deletion.
`409`	`CONCURRENT_UPDATE`	Another write is currently being committed. Read the Study and retry with its latest ETag.
`412`	`CONCURRENT_UPDATE`	The supplied ETag is stale. Re-read, reconcile, and retry.
`422`	`INVALID_STUDY`	Correct every item in `errors`.
`422`	`STUDY_NOT_READY`	Resolve every launch issue before setting `status` to `IN_PROGRESS`.
`428`	`CONCURRENT_UPDATE`	`If-Match` is missing. Read the resource and send its current ETag.

Invitation endpoints currently use two different unsupported-resource responses. Listing invitations for an in-product survey returns 422 INVITATIONS_NOT_SUPPORTED. Creating invitations for an in-product survey returns 400 with the legacy { "error": "Survey is not a link survey" } envelope. Handle both until the API is normalized. Translation endpoints can additionally return UNSUPPORTED_TRANSLATION_LOCALE, TRANSLATION_ENQUEUE_FAILED, TRANSLATION_GENERATION_FAILED, or TRANSLATION_JOB_NOT_CANCELLABLE. Inspect the job status before retrying an asynchronous operation.

Editable states

Settings and authored content can be changed while a Study is DRAFT or PAUSED. Some resources also accept the initial internal state immediately after creation. Public lifecycle transitions are:

DRAFT → IN_PROGRESS
IN_PROGRESS → PAUSED, COMPLETED, or ARCHIVED
PAUSED → IN_PROGRESS, COMPLETED, or ARCHIVED
COMPLETED → ARCHIVED

ARCHIVED is terminal. Send a lifecycle update by itself; do not combine status with settings in the same PATCH.

Legacy compatibility errors

The Study API refuses to reinterpret a stored legacy graph when doing so could change behavior. Compatibility errors are deliberate safeguards:

UNSUPPORTED_TARGETING protects targeting that cannot be expressed by the public targeting schema.
UNSUPPORTED_STUDY_DEFINITION protects unsupported Question or layout structures.
UNSUPPORTED_TRANSLATION_DEFINITION protects translations that cannot be represented completely.

Do not clear or replace the resource merely to bypass the error. Review the Study in Sprig and contact support@sprig.com when migration is required.

​Validate before launch

​Common response codes

​Editable states

​Legacy compatibility errors

Validate before launch

Common response codes

Editable states

Legacy compatibility errors