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",
    "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30"
  }
}

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`).
`requestId`	string	Unique id for this request, identical to the `X-Request-ID` response header. Quote it when contacting support.

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, including an API key whose account role is not allowed to perform it.
`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 upstream dependency is unavailable.

Request ids

Every error response carries a requestId, and every response (error or not) carries the same value in the X-Request-ID response header. Quote it when you report a problem: it identifies the exact request in our logs. If you send your own X-Request-ID header, we propagate it instead of generating one, so your trace id and ours match. Inside a batch account creation response the per-item error object has no requestId. That call returns HTTP 200 and has one id for the whole batch: read it from the X-Request-ID header.

Authentication failures vs. authentication outages

Two different situations used to look identical. They no longer do:

authentication_required (401) means the key was rejected. Check the key, or rotate it. Retrying does not help.
service_unavailable (503) on an authenticated endpoint means we could not reach the authentication service. Your key is fine. Retry with backoff.
rate_limit_exceeded (429) means too many authentication attempts in a short window.

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.
Account creation requires an institutional key — a doctor-scoped key calling account creation is rejected with permission_denied (403), not service_unavailable. Use the institution’s key. See the example below.

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",
    "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30"
  }
}

Invalid API key

{
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid API key.",
    "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30"
  }
}

Resource not found

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "No session scribe found for the given consultation ID.",
    "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30"
  }
}

Consultation ID conflict

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_conflict",
    "message": "consultationInternalId is already in use by a different consultation.",
    "param": "consultationInternalId",
    "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30"
  }
}

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"
        }
      ]
    },
    "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30"
  }
}

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.",
    "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30"
  }
}

Permission denied on account creation

{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "Your API key is not allowed to create accounts. Account creation requires an institutional API key; this key is scoped to a doctor account.",
    "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30"
  }
}

Getting Started

Core Concepts

Accounts & Patients

Reference

Error response format

Error types

Error codes

Request ids

Authentication failures vs. authentication outages

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

Permission denied on account creation

​Error response format

​Error types

​Error codes

​Request ids

​Authentication failures vs. authentication outages

​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

​Permission denied on account creation

Error response format

Error types

Error codes

Request ids

Authentication failures vs. authentication outages

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

Permission denied on account creation