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

# Error Handling

> HTTP status codes and error response format

## Error response format

Every error response follows a consistent envelope structure:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.",
    "param": "idCountry"
  }
}
```

| Field     | Type           | Description                                                                                                                          |
| --------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `type`    | string         | Broad error category for high-level handling.                                                                                        |
| `code`    | string         | Machine-readable error code. Clients should switch on this value.                                                                    |
| `message` | string         | Human-readable error message ending with a period.                                                                                   |
| `param`   | string or null | The request field that caused the error, if applicable.                                                                              |
| `details` | object or null | Optional structured, machine-readable context for the error. Only present on error codes that need it (e.g. `cdss_review_required`). |

## Error types

| Type                    | Description                                              |
| ----------------------- | -------------------------------------------------------- |
| `invalid_request_error` | The request is malformed or contains invalid parameters. |
| `authentication_error`  | Authentication failed (missing or invalid API key).      |
| `permission_error`      | The API key does not have permission for this operation. |
| `api_error`             | An internal or upstream service error occurred.          |

## Error codes

| Code                      | HTTP Status | Description                                                                                         |
| ------------------------- | ----------- | --------------------------------------------------------------------------------------------------- |
| `parameter_missing`       | 400         | A required field is missing from the request body.                                                  |
| `parameter_invalid`       | 400         | A field value is malformed or not accepted.                                                         |
| `account_invalid`         | 400         | The account associated with the API key is misconfigured.                                           |
| `authentication_required` | 401         | Missing or invalid API key.                                                                         |
| `permission_denied`       | 403         | Insufficient permissions for this operation.                                                        |
| `resource_not_found`      | 404         | The requested resource does not exist.                                                              |
| `resource_conflict`       | 409         | A resource with the given identifier already exists.                                                |
| `cdss_review_required`    | 428         | The doctor has pending CDSS suggestions awaiting review; see [CDSS review gate](#cdss-review-gate). |
| `rate_limit_exceeded`     | 429         | Too many requests in a short window; retry after a short wait.                                      |
| `service_unavailable`     | 503         | An external dependency is temporarily down.                                                         |

## API key errors

API-key lifecycle failures reuse the standard codes above:

* **Invalid expiration** — an `apiKeyConfig.validForDays` (on account creation) or a `validForDays` (on [regeneration](/scribe-api/accounts#regenerating-an-api-key)) outside the allowed range **1–365** is rejected with `parameter_invalid` (400).
* **Rate-limited regeneration** — more than one regeneration for the same account within 2 minutes returns `rate_limit_exceeded` (429).
* **Invalid or expired key** — a revoked, unknown, or **expired** API key is rejected at authentication with `authentication_required` (401) and the message "Invalid API key." A missing `Authorization` header returns the same code with the message "API key is required." An expired key is **not** reported with a distinct code — it looks exactly like an invalid key, so [rotate the account's key](/scribe-api/accounts#regenerating-an-api-key) to recover.
* **Publishable key used directly** — a publishable (`pk_`) key presented as a Bearer token to any endpoint returns `permission_denied` (403): "Publishable keys cannot call the API directly…". Publishable keys are [exchange-only](/scribe-api/authentication#key-types) (browser embed); use your **secret** key for API calls.

## CDSS review gate

`GET /scribe-sessions/{id}` and `GET /medical-record-configurations` are hard-blocked with
`cdss_review_required` (428) for a doctor-scoped API key when their institution has enabled
the CDSS pending-review gate and the doctor has at least one unreviewed CDSS suggestion within
the institution's configured window (default 7 days). Institutional-scoped keys are never
gated. The response's `error.details.pendingConsultations` array lists the blocking sessions,
each with a `url` pointing directly at the consultation in scribe-web where the doctor accepts
or rejects the pending suggestions — once every listed suggestion is reviewed, the same request
succeeds immediately (no caching).

## Examples

### Missing required field

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "name is required.",
    "param": "name"
  }
}
```

### Invalid API key

```json theme={null}
{
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid API key."
  }
}
```

### Resource not found

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "No session scribe found for the given consultation ID."
  }
}
```

### Consultation ID conflict

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_conflict",
    "message": "consultationInternalId is already in use by a different consultation.",
    "param": "consultationInternalId"
  }
}
```

### CDSS review required

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "cdss_review_required",
    "message": "This doctor has 1 pending CDSS suggestion awaiting review from the last 7 days. The API is blocked by your institution until the suggestions are reviewed. Open the consultation(s) to accept or reject them: https://scribe.telepatia.ai/consultations/session-abc-123.",
    "details": {
      "pendingConsultations": [
        {
          "sessionId": "session-abc-123",
          "url": "https://scribe.telepatia.ai/consultations/session-abc-123"
        }
      ]
    }
  }
}
```

### Rate limit exceeded

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "rate_limit_exceeded",
    "message": "Too many API key regenerations. Try again in a couple of minutes."
  }
}
```