> ## 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.

# Form Filling API Error Messages

> Learn about the error messages returned by the Suki Form filling 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 Form filling 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 Form filling 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="form-filling-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="form-filling-api-error-messages-filter-panel" className="api-error-messages-filter-panel not-prose" role="dialog" aria-label="Filter Form filling 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">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">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">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="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="feedback">
    ## 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             |
  </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>