API Error Messages

This page lists the error messages returned by the Suki APIs. All error messages are returned in JSON format as shown in the example below.

JSON

{
  "code": 16,
  "message": "invalid sdp token",
  "details": []
}

The code field in the JSON body is a numeric status code. Suki maps it to the HTTP status on the response. See Status code to HTTP mapping for the full mapping. Each table row lists an error id: a stable name you can use in client code. In responses, that value appears in the message field, either as the full string or as a prefix (for example invalid_sdp_token or invalid_sdp_token: …). Match on the id exactly or by prefix when you handle errors in your integration.

Common errors

These are some common errors that can occur across all Suki REST APIs.

Error id	Code	Description
`invalid_sdp_token`	401	Missing, expired, or invalid `sdp_suki_token`
`permission_denied`	403	General authorization failure
`insufficient_scope`	403	`method not allowed due to insufficient scope. Need: sdp.write`
`sbac_denied`	403	Organization not accessible to partner (SBAC)
`provider_not_registered`	401	Clinician not registered via `/auth/register`
`provider_user_inactive`	412	Provider user is not ACTIVATED/LICENSE_PENDING
`missing_sdp_provider_id_header`	400	`sdp_provider_id` header required (single_auth)
`invalid_sdp_provider_id`	400	`sdp_provider_id` fails partner regex
`request_cancelled`	499	Request cancelled by client
`request_timeout`	504	Request timed out
`internal_server_error`	500	Unexpected server error

Ambient

These are some common errors that can occur while implementing the Ambient workflow using the REST APIs.

Error id	Code	Description
`invalid_ambient_id_format`	400	`ambient_session_id` is not a valid UUID on create
`invalid_request`	400	Request body failed validation
`invalid_end_session_request`	400	End session request failed validation
`invalid_cancel_session_request`	400	Cancel session request failed validation
`invalid_context_request`	400	Context body failed validation (specialty, role, visit type, etc.)
`invalid_encryption_hash`	400	Encryption hash must be exactly 64 characters
`ambient_session_id_required`	400	`ambient_session_id` is required (recording)
`invalid_ambient_session_id`	404	Ambient session ID not found
`ambient_session_not_found`	404	Ambient session not found on end
`session_wrong_state`	412	Session is not in CREATED state (includes current status)
`session_job_type_unsupported`	412	Session job type does not support EndSession
`session_in_progress`	409	Concurrent session conflict (for example session in progress on WEB)
`transcripts_retention_exceeded`	404	Transcripts older than 7 days are not available
`content_retention_exceeded`	404	Content for session older than 7 days is not available
`encounter_content_retention_exceeded`	404	Content for encounter older than 7 days is not available
`structured_data_retention_exceeded`	404	Structured data for session older than 7 days is not available
`encounter_structured_data_retention_exceeded`	404	Structured data for encounter older than 7 days is not available
`invalid_encounter_id`	404	Encounter ID not found
`no_appointment_found`	404	No appointment found for `emr_encounter_id`
`missing_emr_encounter_id`	400	`emr_encounter_id` is required (list encounter notes)
`missing_user_id`	400	`user_id` missing from token (list encounter notes)
`missing_organization_id`	400	`organization_id` missing from token (list encounter notes)
`error_creating_session`	500	Error creating ambient session
`error_ending_session`	500	Internal error ending session
`error_streaming_audio`	500	Internal error during `/ws/stream`
`client_disconnected`	499	WebSocket client disconnected during stream
`unknown_request_type`	400	Unknown message type on `/ws/stream`
`error_extracting_ambient_session_id`	400	Ambient session ID missing from WebSocket/metadata
`error_adding_context`	500	Internal error adding/updating session context
`error_processing_context`	500	Internal error processing context payload
`error_generating_presigned_url`	500	Internal error generating offline audio upload URL
`error_fetching_recording`	500	Internal error fetching session recording
`client_metrics_log_failed`	500	Client metrics could not be logged
`error_resolving_encounter`	500	Internal error resolving encounter (list notes)
`error_fetching_encounter_notes`	500	Internal error fetching encounter notes

Form Filling

These are some common errors that can occur while implementing the Form Filling workflow using the REST APIs.

Error id	Code	Description
`invalid_ambient_id_format`	400	`ambient_session_id` is not a valid UUID on create
`invalid_request`	400	Create form-filling session request failed validation
`invalid_end_form_filling_session_request`	400	End form-filling session request failed validation
`invalid_context_request`	400	Form-filling context body failed validation
`form_filling_values_empty`	400	`form_filling.values` must not be empty
`invalid_form_template_id`	400	Form template ID invalid
`invalid_target_emr`	400	`target_emr` value not supported
`invalid_ambient_session_id`	404	Form-filling session ID not found
`ambient_session_not_found`	404	Session not found on end
`session_not_form_filling`	412	Session is not a form-filling job
`session_wrong_state`	412	Session is not in CREATED state
`template_id_required`	412	At least one template ID is required
`form_metadata_missing_ids`	412	Each form metadata entry must include a template ID or form ID
`form_metadata_read_failed`	412	Could not read form metadata in session job input
`form_metadata_invalid`	412	Invalid form metadata in session job input
`structured_data_retention_exceeded`	404	Structured data older than 7 days is not available
`medical_form_not_found`	404	Medical form not found
`error_creating_session`	500	Error creating form-filling session
`error_ending_session`	500	Internal error ending form-filling session
`error_adding_context`	500	Internal error adding/updating form-filling context

Dictation

These are some common errors that can occur while implementing the Dictation workflow using the REST APIs.

Error id	Code	Description
`invalid_transcription_session_id_format`	400	`transcription_session_id` is not a valid UUID
`invalid_request`	400	Transcription request failed validation
`error_extracting_transcription_session_id`	400	Transcription session ID missing from WebSocket/metadata
`invalid_transcription_session_id`	404	Transcription session ID not found
`transcription_session_not_found`	500	No transcription session found for given ID
`session_job_type_unsupported`	412	Session job type does not support EndTranscriptionSession
`transcription_session_completed`	412	Transcription session is already completed
`transcription_session_not_accepting`	412	Transcription session is not accepting new speech sessions
`error_creating_transcription_session`	500	Error creating transcription session
`error_ending_transcription_session`	500	Internal error ending transcription session
`error_creating_transcription_stream`	500	Internal error creating `/ws/transcribe` stream
`error_receiving_audio`	500	Internal error receiving audio on transcription stream
`error_sending_audio`	500	Internal error sending audio on transcription stream
`error_ending_transcription`	500	Internal error ending transcription stream
`error_reading_transcripts`	500	Internal error reading transcripts from transcription service
`client_disconnected`	499	WebSocket client disconnected during transcribe
`unknown_request_type`	400	Unknown message type on `/ws/transcribe`

Feedback

These are some common errors that can occur while implementing the Feedback workflow using the REST APIs.

Ambient feedback

Error id	Code	Description
`invalid_request`	400	Feedback request failed validation
`ambient_session_id_required`	400	`ambient_session_id` is required
`invalid_uuid_format`	400	`ambient_session_id` is not a valid UUID
`feedback_required`	400	`feedback` object is required
`rating_feedback_required`	400	`ratingFeedback` is required
`invalid_entity`	400	Only `CONTENT` entity is supported for ambient feedback
`invalid_rating_range`	400	`minRating` must be less than `maxRating`
`rating_below_min`	400	`rating` must be >= `minRating`
`rating_above_max`	400	`rating` must be <= `maxRating`
`negative_min_rating`	400	`minRating` must be >= 0
`comments_too_long`	400	`qualitativeComments` exceeds 2000 characters
`failed_get_session`	500	Failed to get ambient session for feedback
`failed_submit_feedback`	500	Failed to submit feedback to feedback service

Form-filling feedback

Error id	Code	Description
`invalid_request`	400	Feedback request failed validation
`ambient_session_id_required`	400	`ambient_session_id` is required
`invalid_uuid_format`	400	`ambient_session_id` is not a valid UUID
`payload_required`	400	`payload` is required
`feedback_required`	400	`feedback` object is required
`rating_feedback_required`	400	`ratingFeedback` is required
`feedback_metadata_nil`	400	Feedback metadata is nil
`form_id_required`	400	`form_id` is required in feedback metadata
`invalid_entity`	400	Only `AMBIENT_GENERATED_MEDICAL_FORM` entity is supported
`invalid_rating_range`	400	`minRating` must be less than `maxRating`
`session_not_form_filling`	412	Session is not a form-filling job
`medical_form_not_found`	404	Medical form not found for given `form_id`
`failed_get_session`	500	Failed to get form-filling session for feedback
`failed_submit_feedback`	500	Failed to submit feedback to feedback service

Notification

These are some common errors that can occur while implementing the Notification workflow using the REST APIs.

Success payload

Field	Description
`status`	`"success"`
`session_id`	Session that completed
`encounter_id`	Parent encounter ID
`sessions`	Ordered list of session IDs in encounter
`_links`	HATEOAS links to status, transcripts, content, structured-data

Failure payload

Error id	Code	Description
`ERROR_CODE_UNSPECIFIED`	—	Failure reason unknown or not classified
`ERROR_CODE_NOTIFICATION_GENERATION_FAILURE`	—	Notification payload generation failed
`ERROR_CODE_TRANSCRIPTION`	—	Swagger example only, not in proto enum today

Field	Description
`status`	`"failure"`
`session_id`	Session that failed
`encounter_id`	Parent encounter ID
`error_code`	Machine-readable error code (see table above)
`error_detail`	Human-readable failure details from job output

Preferences

These are some common errors that can occur while implementing the Preferences workflow using the REST APIs.

Error id	Code	Description
`invalid_request`	400	Preferences request failed validation
`update_paths_required`	400	`update_paths` field mask is required
`preference_required`	400	`preference` object is required
`personalization_preference_required`	400	`personalization_preference` is required
`verbosity_or_section_format_required`	400	At least one of `verbosity` or `section_format` must be provided
`invalid_preferences_format`	400	Preferences could not be converted to internal format
`invalid_verbosity`	400	Invalid verbosity enum value
`invalid_section_format`	400	Invalid section format enum value
`error_updating_preferences`	500	Internal error updating user preferences via ms-preferences

Status code to HTTP mapping

This table maps the status names returned by the Suki APIs to the corresponding HTTP status codes.

Status name	HTTP
`InvalidArgument`	400
`Unauthenticated`	401
`PermissionDenied`	403
`NotFound`	404
`AlreadyExists`	409
`Aborted`	409
`FailedPrecondition`	412
`Unimplemented`	501
`Unavailable`	503
`Internal`	500
`Canceled`	499
`DeadlineExceeded`	504

​Common errors

​Ambient

​Form Filling

​Dictation

​Feedback

​Ambient feedback

​Form-filling feedback

​Notification

​Success payload

​Failure payload

​Preferences

​Status code to HTTP mapping