Error Handling

Error response format

Every error response follows a consistent envelope structure:

{
  "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.
`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) 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 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 (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

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "name is required.",
    "param": "name"
  }
}

Invalid API key

{
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid API key."
  }
}

Resource not found

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

Consultation ID conflict

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

CDSS review required

{
  "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

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

Getting Started

Consultations

Scribe Sessions

Clinical Decision Support

Webhooks

Smart Templates

Session Templates

Accounts

Patients

Reference

Error response format

Error types

Error codes

API key errors

CDSS review gate

Examples

Missing required field

Invalid API key

Resource not found

Consultation ID conflict

CDSS review required

Rate limit exceeded

​Error response format

​Error types

​Error codes

​API key errors

​CDSS review gate

​Examples

​Missing required field

​Invalid API key

​Resource not found

​Consultation ID conflict

​CDSS review required

​Rate limit exceeded

Error response format

Error types

Error codes

API key errors

CDSS review gate

Examples

Missing required field

Invalid API key

Resource not found

Consultation ID conflict

CDSS review required

Rate limit exceeded