Errors & status codes

Name: VitalView AI
Price: 233 INR

The error envelope, every error code, and retry guidance.

Every error response uses one envelope:

{
  "error": {
    "code": "study_not_found",
    "message": "No study 'a1b2c3d4' for this organization"
  }
}

Some errors include extra context fields next to code and message (for example detected_series on series-selection failures).

Error codes

HTTP	Code	When	What to do
401	`invalid_api_key`	Missing or unknown `X-API-Key`	Check the header and key value
403	`key_revoked`	Key was revoked	Use your replacement key
400	`unsupported_file_type`	File is not `.dcm` or `.zip`	Repackage the study
400	`no_files` / `no_files_uploaded`	Study created but nothing uploaded	PUT files to the presigned URLs, then retry `process`
404	`study_not_found`	Unknown study id for your org	Check the `study_id` from the create response
404	`results_not_ready`	Report/findings/images before completion	Poll `GET /studies/{id}` until `complete`
409	`already_processing`	Second `process` call	Idempotent; use the `scan_id` in the response
422	`no_processable_series`	No usable DICOM series found	Inspect `detected_series` reasons; send a different series
422	`series_not_found`	`series_uid` not in the upload	Check the UID against `detected_series`
422	`validation_error`	Malformed request body	See `details` for field errors
503	`inference_unavailable`	Processing temporarily unavailable	Retry with backoff
503	`storage_unavailable` / `auth_unavailable`	Upstream dependency issue	Retry with backoff

5xx responses: retry with exponential backoff (for example 1s, 4s, 16s, then alert).
First request after idle can take several seconds while capacity warms up. Set client timeouts to at least 90 seconds and treat a timeout as retryable.
Presigned URL 403: the URL expired (1 hour). Create a new study and re-upload.
4xx responses other than 409: do not retry unchanged; fix the request.
POST /studies/{id}/process is safe to retry: a duplicate call returns 409 already_processing and never dispatches twice.

Status	Meaning
`uploaded`	Waiting for `process`
`queued`	Waiting for a GPU worker
`materializing`	DICOM conversion in progress
`processing`	AI pipeline running
`complete`	Results available
`error`	Failed; `error` field has the reason