Skip to main content

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 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.

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

Clave API inválida

Recurso no encontrado

Conflicto de ID de consulta

Revisión de CDSS requerida

Límite de solicitudes excedido