Erros

Toda requisição com falha a /v1 retorna um documento de problema RFC 9457 com o tipo de conteúdo application/problem+json. Todo problema tem um code estável: decida por ele, nunca pelo texto destinado a pessoas.

O documento de problema

Accept-Language: pt

{
  "type": "https://docs.muveya.com/errors/orders.not_found",
  "title": "Pedido não encontrado",
  "status": 404,
  "detail": "O pedido solicitado não existe neste espaço de trabalho.",
  "instance": "/v1/orders/66d0a1f0c0ffee0000000599",
  "code": "orders.not_found",
  "requestId": "3c9f1e7a-5b2d-4a8e-9f60-7d1c2b3a4e5f"
}

O documento sempre tem exatamente estes sete campos, e nenhum outro.

Campo	O que é
`type`	Um identificador do tipo de problema, formado por `https://docs.muveya.com/errors/` seguido do `code`. É um identificador, não uma página que você precise abrir.
`title`	Um resumo curto do tipo de problema, no idioma do seu cabeçalho `Accept-Language` (`en`, `es` ou `pt`; em inglês nos demais casos).
`status`	O código de status HTTP, repetido no corpo.
`detail`	Uma explicação para pessoas, no mesmo idioma de `title`. Não é um contrato: o texto pode mudar.
`instance`	O caminho da requisição, sem a query string.
`code`	O identificador estável do problema. Em inglês, igual em todos os idiomas. É por ele que seu código deve decidir.
`requestId`	O id da requisição. Coincide com o cabeçalho de resposta `x-request-id`. Inclua-o quando escrever para team@muveya.com.

Trate os erros em dois níveis: primeiro os valores de code que sua integração conhece e depois o status HTTP como alternativa para qualquer código que ela ainda não conheça. Novos códigos podem surgir dentro de /v1 (veja Versionamento e estabilidade).

Falhas inesperadas sempre viram um 500 com o código common.internal_error. Detalhes internos, stack traces e mensagens de banco de dados nunca aparecem em uma resposta.

Códigos que quem chama `/v1` pode receber

`code`	Status	Retornado por	Significado	O que fazer
`common.invalid_request`	400	Listas paginadas, análises, exportações	A requisição não pode ser processada. Veja Causas do erro 400.	Corrija o parâmetro ou o corpo. Repetir a mesma requisição falha de novo.
`api_keys.invalid`	401	Todas as operações	A chave está ausente, malformada, é desconhecida ou foi revogada, seu membro não está mais ativo ou sua clínica odontológica está suspensa. Uma única resposta para todas as causas.	Confira o cabeçalho `Authorization: Bearer` e depois verifique o estado da chave com o membro que a pediu. Veja Autenticação.
`api_keys.scope_missing`	403	Todas as operações, exceto `GET /v1/me`	A chave é válida, mas não tem um escopo que a operação exige.	Compare `GET /v1/me` com Escopos e peça uma chave com os escopos certos.
`common.forbidden`	403	Qualquer operação, como verificação de segurança	A operação não é permitida para quem chama. Em `/v1`, ela reforça a verificação de escopos, e uma chave que tem o escopo da operação não chega a recebê-la.	Confira os escopos da chave. Se estiverem certos, escreva para team@muveya.com com o `requestId`.
`catalog.item_not_found`	404	`GET /v1/catalog/items/{itemId}`	Não existe insumo com esse id nesta clínica odontológica.	Confira o id. Insumos de outra clínica odontológica nunca ficam visíveis.
`inventory.box_not_found`	404	`GET /v1/inventory/boxes/{boxId}` e suas rotas `/balance` e `/movements`	Não existe caixa com esse id nesta clínica odontológica.	Confira o id (um id de caixa, não o código impresso da caixa).
`orders.not_found`	404	`GET /v1/orders/{orderId}`	Não existe pedido com esse id nesta clínica odontológica.	Confira o id (um id de pedido, não o número do pedido).
`common.not_found`	404	`GET /v1/fulfillments/{orderId}`, `GET /v1/analytics/exports/{exportId}`, qualquer caminho inexistente	O recurso não existe nesta clínica odontológica. Em um atendimento (`fulfillment`), o pedido pode existir mas ainda não ter registro de entrega (por exemplo, porque ainda aguarda aprovação). Em uma exportação, o id é desconhecido ou a exportação tem mais de 7 dias.	Confira o caminho e o id. Se o pedido for recente, tente de novo depois que ele for aprovado. Se a exportação for antiga, peça uma nova.
`common.too_many_requests`	429	Todas as operações	A chave usou seu orçamento de requisições na janela atual.	Espere os segundos de `Retry-After` e tente de novo. Veja Limites de uso.
`common.internal_error`	500	Qualquer operação	Uma falha inesperada do lado do muveya.	Repita uma leitura mais tarde, aumentando a espera a cada vez. Se persistir, escreva para team@muveya.com com o `requestId`.

Causas do erro 400

Operação	O que provoca `common.invalid_request`
`GET /v1/orders`, `GET /v1/fulfillments`, `GET /v1/inventory/balances`	Um `limit` que não é um número inteiro de 1 a 200; um `cursor` que não pode ser lido; um `status` que não é um dos valores documentados
`GET /v1/analytics/metrics/{metric}`	Um nome de métrica que não está na lista documentada; um `from` ou `to` que não é uma data; um `from` que não é anterior a `to`
`GET /v1/analytics/consumption-trend`	Um `from` ou `to` que não é uma data; um `from` que não é anterior a `to`; uma janela de mais de 366 dias; uma `granularity` diferente de `day` ou `week`
`GET /v1/analytics/briefing`	Um `period` diferente de `daily` ou `weekly`
`POST /v1/analytics/exports`	Um `period` no corpo diferente de `daily` ou `weekly`; um corpo que não é JSON válido

Mesma resposta, motivos diferentes

Algumas respostas cobrem de propósito mais de uma situação, para que a API nunca revele o que existe em outra clínica odontológica:

Um registro de outra clínica odontológica e um registro que não existe retornam o mesmo 404.
Todo problema com uma chave retorna o mesmo 401.

Não crie lógica que tente distinguir esses casos.

Erros no `/mcp`

O endpoint MCP https://api.muveya.com/mcp falha de três formas diferentes. 1. Antes de a sessão MCP começar. Um token de acesso OAuth ausente, expirado ou inválido retorna 401 com um link WWW-Authenticate para os metadados do recurso protegido. Uma chave de API não é aceita. 2. Dentro de uma chamada de ferramenta. Uma ferramenta que falha ainda retorna uma resposta JSON-RPC normal. O resultado tem isError: true e o texto é um 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`	Status	Quando
`common.forbidden`	403	A chave não tem o escopo de que a ferramenta precisa, ou a ferramenta exige uma permissão de membro que uma chave nunca tem (`approvals.list_pending`, `management.pending_decisions`, `fulfillment.get_pick_list`).
`orders.not_found`	404	`orders.get` com um id que não existe nesta clínica odontológica.
`common.invalid_request`	400	Argumentos que o servidor recusa depois de validar o esquema, como uma janela de tempo que `analytics.consumption` não consegue usar.
`common.internal_error`	500	Uma falha inesperada.

No resultado de uma ferramenta, instance é /mcp# seguido do nome da ferramenta.
O title e o detail dos resultados de ferramentas vêm em inglês.
O requestId identifica aquela requisição MCP. Guarde o do resultado da ferramenta quando relatar um problema.
Argumentos que não seguem o esquema de entrada da ferramenta, e nomes de ferramenta desconhecidos, também voltam como um resultado com isError: true, mas com uma mensagem de texto simples em vez de um documento de problema.

3. Erros de protocolo. São objetos de erro JSON-RPC, não documentos de problema:

Status HTTP	`code` JSON-RPC	Quando
`405`	`-32000`	Uma requisição `GET` ou `DELETE` para `/mcp`. Só `POST` é aceito.
`406`	`-32000`	O cabeçalho `Accept` não inclui ao mesmo tempo `application/json` e `text/event-stream`.
`500`	`-32603`	O transporte MCP falhou inesperadamente.
`200`	`-32600`	Leitura do recurso `muveya://tenant/approval-policy-summary`, que uma chave não pode ler. O `data.code` do erro é `common.forbidden`.

Veja Conectar um cliente para uma requisição correta.

Falhas que não são erros HTTP

Uma exportação que falha depois de aceita não retorna um status de erro. O trabalho passa para "status": "failed" com um motivo error legível por máquina. Veja Exportações do resumo gerencial.

Visão geral

Endpoints

O documento de problema

Códigos que quem chama `/v1` pode receber

Causas do erro 400

Mesma resposta, motivos diferentes

Erros no `/mcp`

Falhas que não são erros HTTP

Páginas relacionadas

​O documento de problema

​Códigos que quem chama /v1 pode receber

​Causas do erro 400

​Mesma resposta, motivos diferentes

​Erros no /mcp

​Falhas que não são erros HTTP

​Páginas relacionadas

O documento de problema

Códigos que quem chama `/v1` pode receber

Causas do erro 400

Mesma resposta, motivos diferentes

Erros no `/mcp`

Falhas que não são erros HTTP

Páginas relacionadas