Manejo de errores

Formato de respuesta de error

Cada respuesta de error sigue una estructura de envelope consistente:

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

Campo	Tipo	Descripción
`type`	string	Categoría general del error para manejo de alto nivel.
`code`	string	Código de error legible por máquina. Los clientes deben hacer switch sobre este valor.
`message`	string	Mensaje de error legible por humanos que termina con un punto.
`param`	string o null	El campo de la solicitud que causó el error, si aplica.
`details`	object o null	Contexto estructurado y legible por máquina opcional para el error. Solo presente en códigos de error que lo requieren (p. ej. `cdss_review_required`).
`requestId`	string	Id único de esta solicitud, idéntico al encabezado de respuesta `X-Request-ID`. Cítelo al contactar a soporte.

Tipos de error

Tipo	Descripción
`invalid_request_error`	La solicitud está malformada o contiene parámetros inválidos.
`authentication_error`	La autenticación falló (clave API faltante o inválida).
`permission_error`	La clave API no tiene permiso para esta operación.
`api_error`	Ocurrió un error interno o de un servicio upstream.

Códigos de error

Código	Estado HTTP	Descripción
`parameter_missing`	400	Falta un campo obligatorio en el cuerpo de la solicitud.
`parameter_invalid`	400	El valor de un campo está malformado o no es aceptado.
`account_invalid`	400	La cuenta asociada a la clave API está mal configurada.
`authentication_required`	401	Clave API faltante o inválida.
`permission_denied`	403	Permisos insuficientes para esta operación, incluida una clave API cuyo rol de cuenta no puede realizarla.
`resource_not_found`	404	El recurso solicitado no existe.
`resource_conflict`	409	Ya existe un recurso con el identificador proporcionado.
`cdss_review_required`	428	El doctor tiene sugerencias de CDSS pendientes de revisión; vea Gate de revisión CDSS.
`rate_limit_exceeded`	429	Demasiadas solicitudes en un período corto; reintente tras una breve espera.
`service_unavailable`	503	Una dependencia upstream no está disponible.

Ids de solicitud

Cada respuesta de error lleva un requestId, y cada respuesta (con error o no) lleva el mismo valor en el encabezado X-Request-ID. Cítelo cuando reporte un problema: identifica la solicitud exacta en nuestros registros. Si usted envía su propio encabezado X-Request-ID, lo propagamos en lugar de generar uno, de modo que su id de traza y el nuestro coincidan. Dentro de una respuesta de creación de cuentas por lotes el objeto error de cada elemento no tiene requestId. Esa llamada devuelve HTTP 200 y tiene un solo id para todo el lote: léalo del encabezado X-Request-ID.

Fallas de autenticación frente a caídas de autenticación

Dos situaciones distintas solían verse idénticas. Ya no:

authentication_required (401) significa que la clave fue rechazada. Revise la clave o rótela. Reintentar no ayuda.
service_unavailable (503) en un endpoint autenticado significa que no pudimos alcanzar el servicio de autenticación. Su clave está bien. Reintente con backoff.
rate_limit_exceeded (429) significa demasiados intentos de autenticación en poco tiempo.

Errores de clave API

Las fallas del ciclo de vida de la clave API reutilizan los códigos estándar anteriores:

Vigencia inválida — un apiKeyConfig.validForDays (al crear la cuenta) o un validForDays (al regenerar) fuera del rango permitido 1–365 se rechaza con parameter_invalid (400).
Regeneración limitada por tasa — más de una regeneración para la misma cuenta en 2 minutos devuelve rate_limit_exceeded (429).
Clave inválida o expirada — una clave API revocada, desconocida o expirada se rechaza en la autenticación con authentication_required (401) y el mensaje “Invalid API key.” Un encabezado Authorization faltante devuelve el mismo código con el mensaje “API key is required.” Una clave expirada no se reporta con un código distinto — se ve exactamente como una clave inválida, así que rote la clave de la cuenta para recuperar el acceso.
Clave publicable usada directamente — una clave publicable (pk_) presentada como token Bearer en cualquier endpoint devuelve permission_denied (403): “Publishable keys cannot call the API directly…”. Las claves publicables son solo de intercambio (embed de navegador); use su clave secreta para las llamadas API.
La creación de cuentas requiere una clave institucional — una clave con alcance de doctor que llame a creación de cuentas se rechaza con permission_denied (403), no con service_unavailable. Use la clave de la institución. Vea el ejemplo abajo.

Gate de revisión CDSS

GET /scribe-sessions/{id} y GET /medical-record-configurations se bloquean con cdss_review_required (428) para una clave API con alcance de doctor cuando su institución tiene habilitado el gate de revisión pendiente de CDSS y el doctor tiene al menos una sugerencia de CDSS sin revisar dentro de la ventana configurada por la institución (7 días por defecto). Las claves con alcance institucional nunca se bloquean. El array error.details.pendingConsultations de la respuesta lista las sesiones que bloquean, cada una con una url que apunta directamente a la consulta en scribe-web donde el doctor acepta o rechaza las sugerencias pendientes — una vez revisadas todas las sugerencias listadas, la misma solicitud se completa de inmediato (sin caché).

Ejemplos

Campo obligatorio faltante

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "name is required.",
    "param": "name",
    "requestId": "3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30"
  }
}

Clave API inválida

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

Recurso no encontrado

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

Conflicto de ID de consulta

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

Revisión de CDSS requerida

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

Límite de solicitudes excedido

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

Permiso denegado al crear una cuenta

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

Primeros pasos

Conceptos básicos

Cuentas y pacientes

Referencia

Formato de respuesta de error

Tipos de error

Códigos de error

Ids de solicitud

Fallas de autenticación frente a caídas de autenticación

Errores de clave API

Gate de revisión CDSS

Ejemplos

Campo obligatorio faltante

Clave API inválida

Recurso no encontrado

Conflicto de ID de consulta

Revisión de CDSS requerida

Límite de solicitudes excedido

Permiso denegado al crear una cuenta

​Formato de respuesta de error

​Tipos de error

​Códigos de error

​Ids de solicitud

​Fallas de autenticación frente a caídas de autenticación

​Errores de clave API

​Gate de revisión CDSS

​Ejemplos

​Campo obligatorio faltante

​Clave API inválida

​Recurso no encontrado

​Conflicto de ID de consulta

​Revisión de CDSS requerida

​Límite de solicitudes excedido

​Permiso denegado al crear una cuenta

Formato de respuesta de error

Tipos de error

Códigos de error

Ids de solicitud

Fallas de autenticación frente a caídas de autenticación

Errores de clave API

Gate de revisión CDSS

Ejemplos

Campo obligatorio faltante

Clave API inválida

Recurso no encontrado

Conflicto de ID de consulta

Revisión de CDSS requerida

Límite de solicitudes excedido

Permiso denegado al crear una cuenta