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

# Patient Summary Error Messages

> Learn about the error messages returned by the Suki Patient Summary 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 error scenarios for the Patient Summary APIs. All error messages are returned in JSON format as shown below.

```json theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "code": 16,
  "message": "invalid sdp token",
  "details": []
}
```

The `code` field contains the numeric gRPC status code. Suki maps this value to the corresponding HTTP status code in the response. For the complete mapping, see [Status code to HTTP mapping](#status-code-to-http-mapping).

Each error in the following tables includes an **error ID**, which is a stable identifier for that error. Use the error ID in your application to identify and handle specific error conditions.

In API responses, the error ID is returned in the message field. Depending on the error, the message field may contain only the error ID or the error ID followed by additional details. For example:

* `invalid_sdp_token`.
* `invalid_get_patient_summary_request: patient_id is required`.

When handling errors, check whether the `message` field matches the error ID exactly or starts with it.

<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 Patient Summary 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="patient-summary-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="patient-summary-api-error-messages-filter-panel" className="api-error-messages-filter-panel not-prose" role="dialog" aria-label="Filter Patient Summary 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">Validation</span>

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

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

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

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

              <input type="checkbox" className="api-error-messages-filter-checkbox" data-api-error-filter="source" />
            </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 can occur across all Patient Summary 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` (Trigger and Generate only) |
    | `invalid_or_missing_partner_id`       | 403  | Partner ID missing or invalid in token claims                                               |
    | `failed_to_retrieve_partner`          | 403  | Failed to retrieve partner details                                                          |
    | `invalid_organization_or_user_claims` | 403  | READWRITE partner with invalid organization or user ID claims                               |
    | `missing_sdp_provider_id_header`      | 400  | `sdp_provider_id` header required (single\_auth partners)                                   |
    | `invalid_sdp_provider_id`             | 400  | `sdp_provider_id` fails partner regex                                                       |
    | `provider_not_registered`             | 401  | Clinician not registered via `/auth/register`                                               |
    | `provider_user_inactive`              | 412  | Provider user is not active                                                                 |
    | `permission_denied`                   | 403  | Partner does not have access to the summary organization (SBAC; Get / PreVisit / Status)    |
    | `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="validation">
    ## Validation

    These errors occur when request validation fails for Patient Summary APIs.

    | Error id                                             | Code | APIs                    | Description                                                                                                |
    | :--------------------------------------------------- | :--- | :---------------------- | :--------------------------------------------------------------------------------------------------------- |
    | `invalid_trigger_patient_summary_generation_request` | 400  | Trigger                 | Trigger schedule request failed validation                                                                 |
    | `fhir_practitioner_id_required`                      | 400  | Trigger                 | `fhir_practitioner_id` is required (1–64 characters)                                                       |
    | `invalid_generate_patient_summary_request`           | 400  | Generate                | Generate encounter request failed validation                                                               |
    | `fhir_encounter_id_required`                         | 400  | Generate                | `fhir_encounter_id` is required (1–64 characters)                                                          |
    | `fhir_practitioner_id_required`                      | 400  | Generate                | `fhir_practitioner_id` is required (1–64 characters)                                                       |
    | `invalid_get_patient_summary_request`                | 400  | Get                     | Get summary request failed validation                                                                      |
    | `invalid_get_pre_visit_summary_request`              | 400  | PreVisit                | Get pre-visit request failed validation                                                                    |
    | `invalid_get_patient_summary_status_request`         | 400  | Status                  | Get status request failed validation                                                                       |
    | `patient_summary_lookup_id_conflict`                 | 400  | Get / PreVisit / Status | Provide either `patient_summary_id` or both FHIR IDs, not both                                             |
    | `fhir_pair_required`                                 | 400  | Get / PreVisit / Status | Both `fhir_encounter_id` and `fhir_practitioner_id` are required when `patient_summary_id` is not provided |
    | `lookup_id_required`                                 | 400  | Get / PreVisit / Status | Either `patient_summary_id` or both FHIR IDs must be provided                                              |
    | `id_length_invalid`                                  | 400  | Get / PreVisit / Status | Lookup identifiers must be 1–64 characters                                                                 |

    ### Exact error messages

    | Error id                                             | Message prefix / text returned today                                                                   |
    | :--------------------------------------------------- | :----------------------------------------------------------------------------------------------------- |
    | `invalid_trigger_patient_summary_generation_request` | `invalid trigger patient summary generation request: …`                                                |
    | `invalid_generate_patient_summary_request`           | `invalid generate patient summary request: …`                                                          |
    | `invalid_get_patient_summary_request`                | `invalid get patient summary request: …`                                                               |
    | `invalid_get_pre_visit_summary_request`              | `invalid get pre-visit summary request: …`                                                             |
    | `invalid_get_patient_summary_status_request`         | `invalid get patient summary status request: …`                                                        |
    | `patient_summary_lookup_id_conflict`                 | `provide either patient_summary_id or both fhir_encounter_id and fhir_practitioner_id, not both`       |
    | `fhir_pair_required`                                 | `both fhir_encounter_id and fhir_practitioner_id are required when patient_summary_id is not provided` |
    | `lookup_id_required`                                 | `either patient_summary_id or both fhir_encounter_id and fhir_practitioner_id must be provided`        |
  </div>

  <div data-api-error-section="downstream">
    ## Downstream / connector

    These errors occur in downstream services or the connector layer.

    | Error id                                                     | Code         | APIs          | Description                                                         |
    | :----------------------------------------------------------- | :----------- | :------------ | :------------------------------------------------------------------ |
    | `failed_to_generate_patient_summaries_for_fhir_practitioner` | passthrough† | Trigger       | Upstream `ms-patient-summary` failed for provider-schedule generate |
    | `failed_to_generate_patient_summary_for_fhir_encounter`      | passthrough† | Generate      | Upstream failed for encounter generate                              |
    | `failed_to_get_fhir_patient_summary`                         | passthrough† | Get / Status‡ | Patient Summary fetch failed or not found                           |
    | `failed_to_get_fhir_pre_visit_summary`                       | passthrough† | PreVisit      | Pre-visit summary fetch failed or not found                         |
    | `no_patient_summary_job_found`                               | 404          | Status        | No jobber job found for resolved `patient_summary_id`               |
    | `multiple_patient_summary_jobs_found`                        | 412          | Status        | More than one job found for the same `patient_summary_id`           |

    The connector rewrites the message but **preserves the upstream gRPC status code** (for example `NotFound` → 404, `InvalidArgument` → 400, `Unavailable` → 503, `Internal` → 500).

    Status resolves the id via GetPatientSummary when a FHIR lookup is used.

    ### Exact error messages

    | Error id                                                     | Message returned today                                              |
    | :----------------------------------------------------------- | :------------------------------------------------------------------ |
    | `failed_to_generate_patient_summaries_for_fhir_practitioner` | `failed to generate patient summaries for fhir practitioner`        |
    | `failed_to_generate_patient_summary_for_fhir_encounter`      | `failed to generate patient summary for fhir encounter`             |
    | `failed_to_get_fhir_patient_summary`                         | `failed to get fhir patient summary`                                |
    | `failed_to_get_fhir_pre_visit_summary`                       | `failed to get fhir pre visit summary`                              |
    | `no_patient_summary_job_found`                               | `no patient summary job found for patientSummaryID: […]`            |
    | `multiple_patient_summary_jobs_found`                        | `more than one patient summary job found for patientSummaryID: […]` |
  </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>