Form Filling API Error Messages

Look up JSON error codes and messages returned by Form filling API endpoints, with causes and recommended fixes

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.

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

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