Errores

Toda solicitud fallida a /v1 devuelve un documento de problema RFC 9457 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

Accept-Language: es

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

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

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

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

Resumen

Endpoints

El documento de problema

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

Causas del error 400

Misma respuesta, distintas razones

Errores en `/mcp`

Fallas que no son errores HTTP

Páginas relacionadas

​El documento de problema

​Códigos que puede recibir quien llama a /v1

​Causas del error 400

​Misma respuesta, distintas razones

​Errores en /mcp

​Fallas que no son errores HTTP

​Páginas relacionadas

El documento de problema

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

Causas del error 400

Misma respuesta, distintas razones

Errores en `/mcp`

Fallas que no son errores HTTP

Páginas relacionadas