> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Error Messages

> Learn about the various error messages returned by the Suki REST APIs

export const UCSearchIcon = () => <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
    <path fill="none" d="M11 17.5a6.5 6.5 0 1 0 0-13 6.5 6.5 0 0 0 0 13z" />
    <path d="m21 21-4.3-4.3" />
  </svg>;

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 JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "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](#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.

<div data-api-error-messages-root data-applied-api-error-filters="">
  <div className="api-error-messages-toolbar">
    <div className="suki-use-case-search-wrap api-error-messages-search-wrap">
      <span aria-hidden="true">
        <UCSearchIcon />
      </span>

      <input type="search" className="suki-use-case-search" placeholder="Search error id, HTTP code, or description" aria-label="Search API error messages" autoComplete="off" />
    </div>

    <div className="api-error-messages-filter-dropdown">
      <button type="button" className="api-error-messages-filter-trigger" aria-expanded="false" aria-haspopup="dialog" aria-controls="api-error-messages-filter-panel">
        <span className="api-error-messages-filter-trigger-text">Categories</span>

        <span className="api-error-messages-filter-trigger-count" hidden aria-hidden="true" />

        <svg className="api-error-messages-filter-trigger-chevron" xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
          <path d="m6 9 6 6 6-6" />
        </svg>
      </button>

      <div id="api-error-messages-filter-panel" className="api-error-messages-filter-panel not-prose" role="dialog" aria-label="Filter error message categories" hidden>
        <ul className="api-error-messages-filter-list not-prose">
          <li>
            <label className="api-error-messages-filter-option">
              <span className="api-error-messages-filter-option-label">Common</span>

              <input type="checkbox" className="api-error-messages-filter-checkbox" data-api-error-filter="common" />
            </label>
          </li>

          <li>
            <label className="api-error-messages-filter-option">
              <span className="api-error-messages-filter-option-label">Ambient</span>

              <input type="checkbox" className="api-error-messages-filter-checkbox" data-api-error-filter="ambient" />
            </label>
          </li>

          <li>
            <label className="api-error-messages-filter-option">
              <span className="api-error-messages-filter-option-label">Form Filling</span>

              <input type="checkbox" className="api-error-messages-filter-checkbox" data-api-error-filter="form-filling" />
            </label>
          </li>

          <li>
            <label className="api-error-messages-filter-option">
              <span className="api-error-messages-filter-option-label">Dictation</span>

              <input type="checkbox" className="api-error-messages-filter-checkbox" data-api-error-filter="dictation" />
            </label>
          </li>

          <li>
            <label className="api-error-messages-filter-option">
              <span className="api-error-messages-filter-option-label">Feedback</span>

              <input type="checkbox" className="api-error-messages-filter-checkbox" data-api-error-filter="feedback" />
            </label>
          </li>

          <li>
            <label className="api-error-messages-filter-option">
              <span className="api-error-messages-filter-option-label">Notification</span>

              <input type="checkbox" className="api-error-messages-filter-checkbox" data-api-error-filter="notification" />
            </label>
          </li>

          <li>
            <label className="api-error-messages-filter-option">
              <span className="api-error-messages-filter-option-label">Preferences</span>

              <input type="checkbox" className="api-error-messages-filter-checkbox" data-api-error-filter="preferences" />
            </label>
          </li>

          <li>
            <label className="api-error-messages-filter-option">
              <span className="api-error-messages-filter-option-label">HTTP mapping</span>

              <input type="checkbox" className="api-error-messages-filter-checkbox" data-api-error-filter="mapping" />
            </label>
          </li>
        </ul>

        <div className="api-error-messages-filter-actions">
          <button type="button" className="api-error-messages-filter-reset">
            Reset
          </button>

          <button type="button" className="api-error-messages-filter-apply">
            Apply
          </button>
        </div>
      </div>
    </div>
  </div>

  <p className="release-notes-filter-empty api-error-messages-empty" hidden>
    No error messages match this filter or search. Choose another category or clear the search box.
  </p>

  <div data-api-error-section="common">
    ## 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                                         |
  </div>

  <div data-api-error-section="ambient">
    ## 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                              |
  </div>

  <div data-api-error-section="form-filling">
    ## 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            |
  </div>

  <div data-api-error-section="dictation">
    ## 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`                      |
  </div>

  <div data-api-error-section="feedback">
    ## 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             |
  </div>

  <div data-api-error-section="notification">
    ## 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 |
  </div>

  <div data-api-error-section="preferences">
    ## 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      |
  </div>

  <div data-api-error-section="mapping">
    <span id="status-code-to-http-mapping" />

    ## 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  |
  </div>
</div>