> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brelio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errores

> Cada error es un objeto problem de la RFC 9457 con un código estable. Todos los códigos, qué significan y cómo resolverlos.

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

```json theme={null}
{
  "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):

```json theme={null}
{
  "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](https://docs.brelio.com/es/concepts/permissions.md). |
| `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](https://docs.brelio.com/es/concepts/data-areas.md). |
| `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](https://docs.brelio.com/es/concepts/idempotency.md). |
| `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](https://docs.brelio.com/es/concepts/rate-limits.md). | 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](https://docs.brelio.com/es/concepts/concurrency.md). |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.