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

# Errores

> El documento de problema que devuelve toda solicitud fallida, todos los códigos de error que puede recibir quien llama a /v1 o /mcp y qué hacer ante cada uno.

Toda solicitud fallida a `/v1` devuelve un documento de problema [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) con el tipo de contenido `application/problem+json`. Todo problema tiene un `code` estable: decide según ese código, nunca según el texto para personas.

## El documento de problema

```json Accept-Language: es theme={null}
{
  "type": "https://docs.muveya.com/errors/orders.not_found",
  "title": "Pedido no encontrado",
  "status": 404,
  "detail": "El pedido solicitado no existe en este espacio de trabajo.",
  "instance": "/v1/orders/66d0a1f0c0ffee0000000599",
  "code": "orders.not_found",
  "requestId": "3c9f1e7a-5b2d-4a8e-9f60-7d1c2b3a4e5f"
}
```

El documento siempre tiene exactamente estos siete campos, y ningún otro.

| Campo | Qué es |
| - | - |
| `type` | Un identificador del tipo de problema, formado por `https://docs.muveya.com/errors/` seguido del `code`. Es un identificador, no una página que debas abrir. |
| `title` | Un resumen breve del tipo de problema, en el idioma de tu encabezado `Accept-Language` (`en`, `es` o `pt`; en inglés en cualquier otro caso). |
| `status` | El código de estado HTTP, repetido en el cuerpo. |
| `detail` | Una explicación para personas, en el mismo idioma que `title`. **No es un contrato**: la redacción puede cambiar. |
| `instance` | La ruta de la solicitud, sin los parámetros de consulta. |
| `code` | El identificador estable del problema. En inglés, igual en todos los idiomas. **Es lo que tu código debe evaluar.** |
| `requestId` | El id de la solicitud. Coincide con el encabezado de respuesta `x-request-id`. Inclúyelo cuando escribas a [team@muveya.com](mailto:team@muveya.com). |

<Tip>
  Maneja los errores en dos niveles: primero los valores de `code` que tu integración conoce y luego el `status` HTTP como respaldo para cualquier código que todavía no conozca. Pueden aparecer códigos nuevos dentro de `/v1` (consulta [Versionado](/docs/es/api-reference/versioning)).
</Tip>

Las fallas inesperadas siempre se convierten en un `500` con el código `common.internal_error`. Los detalles internos, trazas y mensajes de base de datos nunca aparecen en una respuesta.

## Códigos que puede recibir quien llama a `/v1`

| `code` | Estado | Lo devuelve | Significado | Qué hacer |
| - | - | - | - | - |
| `common.invalid_request` | 400 | Listas paginadas, analítica, exportaciones | La solicitud no se puede procesar. Consulta [Causas del error 400](#causas-del-error-400). | Corrige el parámetro o el cuerpo. Repetir la misma solicitud vuelve a fallar. |
| `api_keys.invalid` | 401 | Todas las operaciones | La clave falta, está mal formada, es desconocida o fue revocada, su miembro ya no está activo o su clínica dental está suspendida. Una misma respuesta para todas las causas. | Revisa el encabezado `Authorization: Bearer` y luego confirma el estado de la clave con el miembro que la pidió. Consulta [Autenticación](/docs/es/api-reference/authentication#respuestas-401-y-403). |
| `api_keys.scope_missing` | 403 | Todas las operaciones excepto `GET /v1/me` | La clave es válida pero le falta un scope que la operación requiere. | Compara `GET /v1/me` con [Scopes](/docs/es/api-reference/scopes) y pide una clave con los scopes correctos. |
| `common.forbidden` | 403 | Cualquier operación, como control de seguridad | La operación no está permitida para quien llama. En `/v1` respalda la verificación de scopes, y una clave que tiene el scope de la operación no llega a recibirlo. | Revisa los scopes de la clave. Si son correctos, escribe a [team@muveya.com](mailto:team@muveya.com) con el `requestId`. |
| `catalog.item_not_found` | 404 | `GET /v1/catalog/items/{itemId}` | No hay un insumo con ese id en esta clínica dental. | Revisa el id. Los insumos de otra clínica dental nunca son visibles. |
| `inventory.box_not_found` | 404 | `GET /v1/inventory/boxes/{boxId}` y sus rutas `/balance` y `/movements` | No hay una caja con ese id en esta clínica dental. | Revisa el id (un id de caja, no el código impreso de la caja). |
| `orders.not_found` | 404 | `GET /v1/orders/{orderId}` | No hay un pedido con ese id en esta clínica dental. | Revisa el id (un id de pedido, no el número de pedido). |
| `common.not_found` | 404 | `GET /v1/fulfillments/{orderId}`, `GET /v1/analytics/exports/{exportId}`, cualquier ruta que no existe | El recurso no existe en esta clínica dental. En un registro de entrega (`fulfillment`), el pedido puede existir pero aún no tener registro de entrega (por ejemplo, porque sigue esperando aprobación). En una exportación, el id es desconocido o la exportación tiene más de 7 días. | Revisa la ruta y el id. Si el pedido es reciente, vuelve a intentarlo cuando haya sido aprobado. Si la exportación es antigua, pide una nueva. |
| `common.too_many_requests` | 429 | Todas las operaciones | La clave usó su presupuesto de solicitudes de la ventana actual. | Espera los segundos de `Retry-After` y vuelve a intentarlo. Consulta [Límites de uso](/docs/es/api-reference/rate-limits). |
| `common.internal_error` | 500 | Cualquier operación | Una falla inesperada del lado de muveya. | Repite una lectura más tarde, esperando cada vez más. Si persiste, escribe a [team@muveya.com](mailto:team@muveya.com) con el `requestId`. |

### Causas del error 400

| Operación | Qué provoca `common.invalid_request` |
| - | - |
| `GET /v1/orders`, `GET /v1/fulfillments`, `GET /v1/inventory/balances` | Un `limit` que no es un número entero de 1 a 200; un `cursor` que no se puede leer; un `status` que no es uno de los valores documentados |
| `GET /v1/analytics/metrics/{metric}` | Un nombre de métrica que no está en la lista documentada; un `from` o `to` que no es una fecha; un `from` que no es anterior a `to` |
| `GET /v1/analytics/consumption-trend` | Un `from` o `to` que no es una fecha; un `from` que no es anterior a `to`; una ventana de más de 366 días; una `granularity` distinta de `day` o `week` |
| `GET /v1/analytics/briefing` | Un `period` distinto de `daily` o `weekly` |
| `POST /v1/analytics/exports` | Un `period` en el cuerpo distinto de `daily` o `weekly`; un cuerpo que no es JSON válido |

### Misma respuesta, distintas razones

Algunas respuestas cubren a propósito más de una situación, para que la API nunca revele qué existe en otra clínica dental:

* Un registro de otra clínica dental y un registro que no existe devuelven el mismo `404`.
* Todo problema con una clave devuelve el mismo `401`.

No construyas lógica que intente distinguir estos casos.

## Errores en `/mcp`

El endpoint MCP `https://api.muveya.com/mcp` falla de tres maneras distintas.

**1. Antes de que empiece la sesión MCP.** Un token de acceso OAuth ausente, vencido o no válido devuelve `401` con un enlace `WWW-Authenticate` a los metadatos del recurso protegido. No se acepta una clave de API.

**2. Dentro de una llamada a una herramienta.** Una herramienta que falla devuelve de todos modos una respuesta JSON-RPC normal. Su resultado tiene `isError: true` y su texto es un documento de problema:

```json theme={null}
{
  "type": "https://docs.muveya.com/errors/common.forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The operation is not allowed.",
  "instance": "/mcp#approvals.list_pending",
  "code": "common.forbidden",
  "requestId": "0f4e2a6c-8d1b-4c3e-a5f7-9b2d4e6f8a0c"
}
```

| `code` | Estado | Cuándo |
| - | - | - |
| `common.forbidden` | 403 | A la clave le falta el scope que la herramienta necesita, o la herramienta necesita un permiso de miembro que una clave nunca tiene (`approvals.list_pending`, `management.pending_decisions`, `fulfillment.get_pick_list`). |
| `orders.not_found` | 404 | `orders.get` con un id que no existe en esta clínica dental. |
| `common.invalid_request` | 400 | Argumentos que el servidor rechaza después de validar el esquema, como una ventana de tiempo que `analytics.consumption` no puede usar. |
| `common.internal_error` | 500 | Una falla inesperada. |

* En el resultado de una herramienta, `instance` es `/mcp#` seguido del nombre de la herramienta.
* El `title` y el `detail` de los resultados de herramientas están en inglés.
* El `requestId` identifica esa solicitud MCP. Tómalo del resultado de la herramienta y consérvalo para cuando nos informes un problema.
* Los argumentos que no cumplen el esquema de entrada de la herramienta, y los nombres de herramienta desconocidos, también vuelven como un resultado con `isError: true`, pero con un mensaje de texto simple en lugar de un documento de problema.

**3. Errores de protocolo.** Son objetos de error JSON-RPC, no documentos de problema:

| Estado HTTP | `code` JSON-RPC | Cuándo |
| - | - | - |
| `405` | `-32000` | Una solicitud `GET` o `DELETE` a `/mcp`. Solo se acepta `POST`. |
| `406` | `-32000` | El encabezado `Accept` no incluye a la vez `application/json` y `text/event-stream`. |
| `500` | `-32603` | El transporte MCP falló de forma inesperada. |
| `200` | `-32600` | Lectura del recurso `muveya://tenant/approval-policy-summary`, que una clave no puede leer. El `data.code` del error es `common.forbidden`. |

Consulta [Conectar un cliente](/docs/es/mcp/connect) para ver una solicitud correcta.

## Fallas que no son errores HTTP

Una exportación que falla después de haber sido aceptada no devuelve un estado de error. Su trabajo pasa a `"status": "failed"` con un motivo `error` legible por máquina. Consulta [Exportaciones](/docs/es/api-reference/exports#si-el-archivo-no-se-genera).

## Páginas relacionadas

* [Autenticación](/docs/es/api-reference/authentication)
* [Límites de uso](/docs/es/api-reference/rate-limits)
* [Paginación](/docs/es/api-reference/pagination)
* [Solución de problemas](/docs/es/help/troubleshooting)


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