Formato de respuesta de error
Cada respuesta de error sigue una estructura de envelope consistente:Tipos de error
Códigos de error
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 unvalidForDays(al regenerar) fuera del rango permitido 1–365 se rechaza conparameter_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 encabezadoAuthorizationfaltante 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 devuelvepermission_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.
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é).