Formato de respuesta de error
Todas las respuestas de error siguen la misma estructura:Tipos de error
Códigos de error
Ids de solicitud
Cada respuesta de error lleva unrequestId, y cada respuesta (con error o no) lleva el
mismo valor en el encabezado de respuesta X-Request-ID. Inclúyelo cuando reportes un problema: identifica
la solicitud exacta en nuestros logs.
Si envías tu propio encabezado X-Request-ID, lo propagamos en lugar de generar uno,
de modo que tu id de traza y el nuestro coincidan.
En la respuesta de una creación de cuentas en lote, el
objeto error de cada elemento no tiene requestId. Esa llamada devuelve HTTP 200 y tiene
un solo id para todo el lote: léelo del encabezado X-Request-ID.
Fallas de autenticación frente a caídas del servicio de autenticación
Antes, dos situaciones distintas se veían idénticas. Ya no:authentication_required(401) significa que la API key fue rechazada. Revisa la API key o rótala. Reintentar no ayuda.service_unavailable(503) en un endpoint autenticado significa que no pudimos contactar el servicio de autenticación. Tu API key está bien. Reintenta con backoff.rate_limit_exceeded(429) significa demasiados intentos de autenticación en poco tiempo.
Errores de API key
Las fallas del ciclo de vida de la API key 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). - Límite de regeneraciones — más de una regeneración para la misma cuenta en 2 minutos devuelve
rate_limit_exceeded(429). - API key no válida o vencida — una API key revocada, desconocida o vencida se rechaza en la autenticación con
authentication_required(401) y el mensaje “Invalid API key.” Si falta el encabezadoAuthorization, se devuelve el mismo código con el mensaje “API key is required.” Una API key vencida no se reporta con un código distinto: se ve exactamente igual que una API key no válida, así que rota la API key de la cuenta para recuperar el acceso. - Clave publicable usada directamente — una clave publicable (
pk_) enviada como token Bearer a cualquier endpoint devuelvepermission_denied(403): “Publishable keys cannot call the API directly…”. Las claves publicables son solo de intercambio (embed en el navegador); usa tu clave secreta para las llamadas a la API. - La creación de cuentas requiere una API key institucional — una API key con alcance de médico que llame a la creación de cuentas se rechaza con
permission_denied(403), no conservice_unavailable. Usa la API key de la institución. Consulta el ejemplo más abajo.
Bloqueo por revisión de CDSS
GET /scribe-sessions/{id} y GET /medical-record-configurations se bloquean por completo con
cdss_review_required (428) para una API key con alcance de médico cuando su institución
tiene habilitado el bloqueo por revisiones pendientes de CDSS y el médico tiene al menos una sugerencia
de CDSS sin revisar dentro de la ventana configurada por la institución (7 días por defecto).
Las API keys con alcance institucional nunca se bloquean. El array error.details.pendingConsultations
de la respuesta lista las sesiones que causan el bloqueo, cada una con una url que apunta directamente a
la consulta en scribe-web donde el médico acepta o rechaza las sugerencias pendientes. Una vez
revisadas todas las sugerencias listadas, la misma solicitud funciona de inmediato (no hay caché).