Ambient & Dictation Error Messages

Look up Ambient and Dictation API error ids, HTTP mappings, and category filters to debug failed REST calls in your integration

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.

Categories

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

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

Content Rewrite

These errors can occur on Rewrite content (POST /api/v1/content/rewrite). Message text for rewrite-specific rows often includes request_id=… for support.

Error id	Code	Description
invalid_sdp_token	401	Missing, expired, or invalid sdp_suki_token (message may be invalid sdp token)
permission_denied	403	General authorization failure (message may be permission denied)
invalid_or_missing_partner_id	403	Invalid or missing Partner ID in token claims
failed_to_retrieve_partner	403	Failed to retrieve partner details
invalid_organization_or_user_claims	403	Invalid organization ID or user ID claims
missing_sdp_provider_id_header	400	sdp_provider_id header required for single_auth partners
invalid_sdp_provider_id	400	Invalid sdp_provider_id
provider_not_registered	401	Clinician not registered via /auth/register
provider_user_inactive	400	Provider user is not active (Rewrite content maps FailedPrecondition to 400)
content_rewrite_not_enabled	403	Content rewrite is not enabled for this partner or user
invalid_rewrite_content_request	400	Rewrite request failed validation. Common causes: instruction is not exactly CONCISE, VERBOSE, or PATIENT_FRIENDLY; selected_text length is outside 1–1024 Unicode runes (default max); context or context.selection is missing; selection.start / selection.end violate 0 <= start <= end; surrounding_content exceeds the same max length when set
failed_to_get_enable_content_rewrite_config	500	Internal error loading the content rewrite entitlement config
failed_to_get_user_specialty	500	Internal error loading the user specialty used for rewrite

Other single-auth identity failures on Rewrite content return 401. When a downstream rewrite service fails, the API can return that service’s mapped HTTP status and message, with request_id=… appended. Keep request_id when you open a support ticket.

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

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