Form Filling API Error Messages

This page lists the error messages returned by the Suki Form filling 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

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

Form filling feedback

These are some common errors that can occur when submitting feedback for a Form filling session.

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

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

​Form filling

​Form filling feedback

​Status code to HTTP mapping

Common errors

Form filling

Form filling feedback

Status code to HTTP mapping