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

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

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":"one-light","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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.