Errores

Los errores responden con Content-Type: application/problem+json y siempre con la misma forma. Por MCP, el mismo objeto llega como resultado de la herramienta con isError: true.

{
  "type": "https://api.brelio.app/problems/operation-forbidden",
  "title": "Forbidden",
  "status": 403,
  "code": "OPERATION_FORBIDDEN",
  "detail": "The credential does not grant patients.administrative.read.",
  "request_id": "4cbc47b2-a8f9-40e4-b0b9-d8d16c099888",
  "params": { "permission": "patients.administrative.read" },
  "hint": "Give the credential the patients.administrative.read permission, or call with one that has it."
}

Campo	Significado
`code`	Identificador estable. Decide con él, nunca con `detail` ni `title`.
`status`	El estado HTTP, repetido.
`detail`	Qué ha pasado, en inglés, para logs y desarrolladores. Puede cambiar.
`hint`	Qué hacer, cuando hay algo que hacer.
`params`	Detalles para máquinas: el permiso que falta, los campos no válidos, el id. Nunca datos de la petición. Siempre presente.
`request_id`	También en la cabecera `x-request-id`. Indícalo cuando pidas ayuda a Brelio.
`retryAfterSeconds`	En `429` y `503`: segundos de espera. También en `Retry-After`.

La web de Brelio muestra estos códigos en español a la clínica, así que el mismo error se lee igual en todas partes.

Entrada no válida

422 OPERATION_INPUT_INVALID lista cada problema por ruta y código, sin repetir los valores (pueden ser datos de pacientes):

{
  "status": 422,
  "code": "OPERATION_INPUT_INVALID",
  "detail": "The input does not match the operation.",
  "params": {
    "issues": [
      { "path": "patientId", "code": "invalid_format" },
      { "path": "start", "code": "invalid_type" }
    ]
  }
}

Reintentar o no

Estado	¿Reintentar?
`400`, `401`, `402`, `403`, `404`, `422`	No. Corrige antes la petición, la credencial o los ajustes de la clínica.
`409`	No tal cual. Vuelve a leer el registro (conflictos de versión), espera (idempotencia en curso) o cambia la petición.
`429`, `503`	Sí, tras `Retry-After` segundos, con la misma `Idempotency-Key`.
`500`	Sí, con espera creciente y la misma `Idempotency-Key`.

Todos los códigos

Estos son los códigos que hoy devuelven la plataforma y sus operaciones. Una operación también puede dejar pasar un código de las reglas propias de Brelio (por ejemplo, un límite del plan), siempre con la misma forma y un detail que lo explica: trata un código desconocido por su status.

Autenticación y acceso

Código	Estado	Significado	Solución
`PLATFORM_UNAUTHENTICATED`	401	No hay credencial bearer, o no es válida, está revocada o ha caducado.	Envía `Authorization: Bearer <credencial>` con una clave o un token válidos.
`PLATFORM_AUTH_UNAVAILABLE`	503	No se ha podido comprobar la credencial ahora.	Reintenta tras `Retry-After` (30 s).
`PLATFORM_ORGANIZATION_NOT_LINKED`	403	La credencial pertenece a una organización o persona sin acceso a Brelio.	Usa una credencial creada en una clínica de Brelio a la que perteneces.
`PLATFORM_ORGANIZATION_AMBIGUOUS`	403	Solo MCP: perteneces a varias clínicas y la conexión no indica ninguna.	Vuelve a conectar y elige la clínica.
`PLATFORM_PLAN_REQUIRED`	402	El plan de la clínica no incluye el acceso a la API.	Un propietario lo añade en Configuración › Suscripción.
`PLATFORM_PLAN_UNAVAILABLE`	503	No se ha podido confirmar ahora el acceso a la API.	Reintenta en 30 s.
`OPERATION_FORBIDDEN`	403	A la credencial, o a la persona que hay detrás, le falta el permiso de `params.permission`.	Usa una credencial con ese permiso. Consulta los permisos.
`CENTER_CONTEXT_FORBIDDEN`	403	El `centerId` enviado no es uno de los centros de quien llama.	Envía un centro que puedas ver, u omítelo.
`DATA_AREA_OFF`	403	La clínica no deja que las integraciones usen el área de datos de la operación (`params.area`).	Un propietario activa el área en Brelio. Consulta las áreas de datos.
`DATA_AREA_UNKNOWN`	403	La operación no tiene área de datos, así que ninguna integración puede ejecutarla.	Comunícalo a Brelio.
`PATIENT_DATA_CONSENT_REQUIRED`	403	No se han aceptado los datos de pacientes para esta credencial. Por MCP, `params.consent_url` enlaza a la página de aceptación.	La persona (o el propietario, en claves de la organización y apps) lo acepta en Brelio; luego reintenta.
`PLATFORM_REVEAL_FORBIDDEN`	403	La operación devuelve un secreto de un solo uso, que MCP no puede entregar a una persona.	Llámala por REST, o crea la credencial en Brelio.

Peticiones

Código	Estado	Significado	Solución
`PLATFORM_ROUTE_NOT_FOUND`	404	No hay ninguna operación en ese método y ruta.	Consulta `GET /v1/openapi.json`.
`MALFORMED_JSON_BODY`	400	El cuerpo no es un objeto JSON.	Envía un objeto JSON con `Content-Type: application/json`.
`OPERATION_INPUT_INVALID`	422	La entrada no encaja con la operación; mira `params.issues`.	Corrige los campos indicados.
`IDEMPOTENCY_KEY_REQUIRED`	400	Una escritura sin una `Idempotency-Key` válida.	Envía un UUID. Consulta la idempotencia.
`OPERATION_IDEMPOTENCY_CONFLICT`	409	La clave ya se usó con otra petición.	Usa una clave nueva para un cambio nuevo.
`OPERATION_IDEMPOTENCY_IN_PROGRESS`	409	La primera petición con esta clave sigue en curso.	Espera y reintenta con la misma clave.
`RATE_LIMITED`	429	Se ha alcanzado un límite de uso.	Espera `Retry-After` segundos.
`PLATFORM_LIMITS_UNAVAILABLE`	503	El limitador no ha respondido; las operaciones con datos de pacientes se cierran.	Reintenta en 5 s.
`PLATFORM_INTERNAL`	500	Solo MCP: un fallo inesperado. No se envía nada sobre él.	Reintenta más tarde; indica el `request_id`.

Una llamada REST que falla de forma inesperada responde 500 con la cabecera x-request-id.

Versiones

Código	Estado	Significado	Solución
`VERSION_CONFLICT`	409	El paciente o la cita cambió desde que lo leíste.	Vuelve a leerlo y reintenta con su nueva `version`. Consulta la concurrencia.

Citas y huecos libres

Código	Estado	Significado	Solución
`APPOINTMENT_NOT_FOUND`	404	No hay ninguna cita con ese id que puedas ver.	Toma los ids de `GET /v1/agenda` o de la respuesta de creación.
`APPOINTMENT_REFERENCE_NOT_FOUND`	404	El paciente, profesional o servicio (`params.what`) no existe o no puedes reservarlo. Los pacientes inactivos no se pueden reservar.	Comprueba el id con la lista correspondiente.
`APPOINTMENT_CENTER_REQUIRED`	422	La clínica tiene varios centros y la cita necesita uno.	Envía `centerId`.
`APPOINTMENT_OVERLAP_DETECTED`	409	La hora ya no está libre para el profesional.	Vuelve a buscar huecos y elige otro.
`APPOINTMENT_PROFESSIONAL_UNAVAILABLE`	422	El profesional no trabaja a esa hora.	Usa un hueco de `GET /v1/availability`.
`APPOINTMENT_RECURRING_UNSUPPORTED`	422	Las citas recurrentes todavía no se pueden cambiar por la API.	Cámbiala en Brelio.
`APPOINTMENT_CANCEL_IN_BRELIO`	409	La cita ya tiene sesión (paciente llegado o después), así que se cancela en Brelio.	Cancélala en Brelio.
`APPOINTMENT_RESCHEDULE_NOT_ALLOWED`	409	El estado de la cita no permite moverla.	Léela; solo se mueven las citas programadas.
`APPOINTMENT_INVALID_STATE_TRANSITION`	409	El cambio no está permitido desde el estado actual de la cita.	Léela y revisa su `status`.
`AVAILABILITY_CENTER_REQUIRED`	422	La clínica tiene varios centros.	Envía `centerId`.
`AVAILABILITY_REFERENCE_NOT_FOUND`	404	El paciente, profesional o servicio (`params.what`) no se puede reservar aquí.	Comprueba el id.

Pacientes

Código	Estado	Significado	Solución
`PATIENT_NOT_FOUND`	404	No hay ningún paciente con ese id que puedas ver. Los archivados no se encuentran.	Busca con `GET /v1/patients`.
`PATIENT_ACTION_NOT_ALLOWED`	409	El estado del paciente no permite el cambio (`params.action`: `edit` o `archive`).	Lee el paciente; si hace falta, cámbialo en Brelio.

Credenciales

Código	Estado	Significado	Solución
`CREDENTIAL_NOT_FOUND`	404	No hay ninguna clave, app o conexión con ese id en la clínica.	Lístalas primero.
`CREDENTIAL_SESSION_REQUIRED`	403	Crear credenciales o revocar otra necesita una persona en Brelio.	Hazlo en Brelio; una credencial solo puede revocarse a sí misma.
`CREDENTIAL_PERMISSION_NOT_HELD`	403	Has intentado dar permisos que no tienes (`params.permissions`).	Pídeselo a alguien que los tenga.
`PLATFORM_CREDENTIALS_UNAVAILABLE`	503	El proveedor de identidad no ha respondido.	Reintenta más tarde.
`PLATFORM_CREDENTIALS_REFUSED`	422	El proveedor de identidad ha rechazado la petición.	Revisa los nombres y los permisos enviados.

Política de datos

Código	Estado	Significado	Solución
`DATA_POLICY_VERSION_CONFLICT`	409	El área cambió desde que la leíste.	Lee `GET /v1/platform-policy` y reenvía con su `version`.
`DATA_POLICY_UNCHANGED`	409	El área ya tiene ese estado.	No hay nada que hacer.
`DATA_POLICY_NEEDS_PERSON`	403	El cambio debe quedar registrado como decisión de una persona.	Usa una credencial personal o Brelio.
`DATA_AREA_ENABLE_IN_BRELIO`	403	Las integraciones solo pueden desactivar áreas.	Un propietario la activa en Brelio.
`PATIENT_DATA_ACCEPT_IN_BRELIO`	403	Los datos de pacientes los acepta una persona en Brelio.	Acéptalos en Brelio.
`PATIENT_DATA_CREDENTIAL_NOT_YOURS`	403	Solo puedes decidir sobre tus propias claves y conexiones.	Pídeselo a un propietario.
`PATIENT_DATA_NOTHING_TO_REVOKE`	409	No hay ninguna aceptación que revocar.	No hay nada que hacer.
`PATIENT_DATA_TERMS_NOT_ACCEPTED`	422	Activar un área de pacientes necesita `acceptTerms: true` y el `termsVersion` leído.	Envía los dos.
`PATIENT_DATA_TERMS_OUTDATED`	409	Las condiciones cambiaron desde que se mostraron.	Muestra las condiciones actuales y envía su versión.
`PATIENT_DATA_TERMS_PENDING`	409	Las condiciones revisadas todavía no están publicadas.	Espera a que se publiquen.

Webhooks

Código	Estado	Significado	Solución
`WEBHOOK_NOT_FOUND`	404	No hay ningún webhook con ese id.	Revisa `GET /v1/webhooks`.
`WEBHOOK_VERSION_CONFLICT`	409	El webhook cambió desde que lo leíste.	Vuelve a leerlo y reintenta con su `version`.
`WEBHOOK_EVENT_TYPE_UNKNOWN`	422	Un tipo de evento de `eventTypes` no existe.	Elige entre los de `GET /v1/webhook-event-types`.
`WEBHOOK_DELIVERY_PENDING`	409	Esa entrega ya está en cola.	Espera; `GET /v1/webhooks/{id}` indica cuándo se intenta.
`WEBHOOK_TEST_RATE_LIMITED`	429	Más de 5 pruebas en un minuto para este webhook.	Espera un minuto.
`WEBHOOK_NOTHING_TO_DO`	404	El webhook ya no existe o ya está desactivado.	No hay nada que hacer.

Empezar

Conceptos

Guías

Referencia MCP

Referencia

Entrada no válida

Reintentar o no

Todos los códigos

Autenticación y acceso

Peticiones

Versiones

Citas y huecos libres

Pacientes

Credenciales

Política de datos

Webhooks

​Entrada no válida

​Reintentar o no

​Todos los códigos

​Autenticación y acceso

​Peticiones

​Versiones

​Citas y huecos libres

​Pacientes

​Credenciales

​Política de datos

​Webhooks

Entrada no válida

Reintentar o no

Todos los códigos

Autenticación y acceso

Peticiones

Versiones

Citas y huecos libres

Pacientes

Credenciales

Política de datos

Webhooks