> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sprig.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and launch validation

> Interpret Study API errors, validate a Study, and resolve launch blockers.

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.

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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](mailto:support@sprig.com) when migration is required.