> ## Documentation Index > Fetch the complete documentation index at: https://docs.telepatia.ai/llms.txt > Use this file to discover all available pages before exploring further. # Manejo de errores > Códigos de estado HTTP y formato de respuesta de error ## Formato de respuesta de error Cada respuesta de error sigue una estructura de envelope consistente: ```json theme={null} { "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" } } ``` | 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`). | ## 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. | | `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](#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 externa está temporalmente caída. | ## 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](/es/scribe-api/accounts#regenerar-una-clave-api)) 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](/es/scribe-api/accounts#regenerar-una-clave-api) 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](/es/scribe-api/authentication#tipos-de-clave) (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 ```json theme={null} { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name" } } ``` ### Clave API inválida ```json theme={null} { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key." } } ``` ### Recurso no encontrado ```json theme={null} { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "No session scribe found for the given consultation ID." } } ``` ### Conflicto de ID de consulta ```json theme={null} { "error": { "type": "invalid_request_error", "code": "resource_conflict", "message": "consultationInternalId is already in use by a different consultation.", "param": "consultationInternalId" } } ``` ### Revisión de CDSS requerida ```json theme={null} { "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" } ] } } } ``` ### Límite de solicitudes excedido ```json theme={null} { "error": { "type": "invalid_request_error", "code": "rate_limit_exceeded", "message": "Too many API key regenerations. Try again in a couple of minutes." } } ```