> ## 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. # Erros > O documento de problema que toda requisição com falha retorna, todos os códigos de erro que quem chama /v1 ou /mcp pode receber e o que fazer em cada caso. Toda requisição com falha a `/v1` retorna um documento de problema [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) 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 ```json Accept-Language: pt theme={null} { "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](mailto: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](/docs/pt/api-reference/versioning)). 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](#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](/docs/pt/api-reference/authentication#respostas-401-e-403). | | `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](/docs/pt/api-reference/scopes) 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](mailto: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](/docs/pt/api-reference/rate-limits). | | `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](mailto: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: ```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` | 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](/docs/pt/mcp/connect) 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](/docs/pt/api-reference/exports#quando-o-trabalho-falha). ## Páginas relacionadas * [Autenticação](/docs/pt/api-reference/authentication) * [Limites de uso](/docs/pt/api-reference/rate-limits) * [Paginação](/docs/pt/api-reference/pagination) * [Solução de problemas](/docs/pt/help/troubleshooting) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.