Saltar al contenido principal

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 un requestId, 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 un validForDays (al regenerar) fuera del rango permitido 1–365 se rechaza con parameter_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 encabezado Authorization, 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 devuelve permission_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 con service_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é).

Ejemplos

Campo obligatorio faltante

API key no válida

Recurso no encontrado

Conflicto de ID de consulta

Revisión de CDSS pendiente

Límite de solicitudes excedido

Permiso denegado al crear una cuenta