{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-parceiros/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Erros","description":"APIs públicas da Movvia para parceiros, estabelecimentos comerciais e clientes de dados veiculares.","meta":[{"name":"theme-color","content":"#7E3DEE"},{"name":"apple-mobile-web-app-title","content":"Movvia Docs"},{"name":"application-name","content":"Movvia Docs"}],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"erros","__idx":0},"children":["Erros"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Todas as respostas de erro seguem o mesmo formato:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"erro\": \"CODIGO_DO_ERRO\",\n  \"mensagem\": \"Descrição legível do problema.\",\n  \"detalhe\": \"Informação adicional opcional.\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"códigos-http","__idx":1},"children":["Códigos HTTP"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Significado geral"},"children":["Significado geral"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Requisição malformada ou campo inválido"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Credenciais ausentes ou inválidas"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sem permissão para o recurso"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Recurso não encontrado"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conflito de estado (pedido já confirmado, chave duplicada)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Dados válidos sintaticamente, mas inválidos semanticamente"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rate limit atingido"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Erro interno da plataforma Movvia"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"catálogo-de-erros-de-aplicação","__idx":2},"children":["Catálogo de erros de aplicação"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Código"},"children":["Código"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status HTTP"},"children":["Status HTTP"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Causa"},"children":["Causa"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Ação recomendada"},"children":["Ação recomendada"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PARCEIRO_ID_AUSENTE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Header ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-parceiro-id"]}," não enviado"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Incluir o header em todas as requisições"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PLACA_INVALIDA"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["422"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Formato de placa não reconhecido"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Validar formato Mercosul (ABC1D23) ou antigo (ABC1234)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PLACA_JA_CADASTRADA"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["409"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Placa já existe na base do parceiro"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Consultar ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /placas/{placa}"]}," antes de cadastrar"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSACAO_NAO_ENCONTRADA"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["404"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transacaoId"]}," não existe ou não pertence ao parceiro"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verificar o ID; revisar logs de webhook"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PEDIDO_JA_CONFIRMADO"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["409"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tentativa de confirmar pedido já em estado terminal"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verificar estado via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /pedidos/{id}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PEDIDO_EXPIRADO"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["409"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pedido passou de 48h sem confirmação"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Criar novo pedido"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IDEMPOTENCY_CONFLICT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["409"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Mesma ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotencyKey"]}," com payload diferente"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Usar chave diferente para a nova operação"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RATE_LIMIT_EXCEEDED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["429"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Limite de requisições atingido"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Aguardar ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-RateLimit-Reset"]}," e retentar"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREDENCIAL_INVALIDA"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," incorreto"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verificar codificação Base64 das credenciais"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"erros-5xx","__idx":3},"children":["Erros 5xx"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Erros de servidor (500, 502, 503, 504) são transitórios. Sempre implemente retry com backoff:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Aguarde 1s, 5s, 30s entre tentativas."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Monitore a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://status.pedagioeletronico.com.br"},"children":["status page"]}," para incidentes em andamento."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Erros 5xx não consomem a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotencyKey"]}," — reenviar com a mesma chave é seguro."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"validação-de-placa","__idx":4},"children":["Validação de placa"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Placas aceitas:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Mercosul: [A-Z]{3}[0-9][A-Z][0-9]{2}   → ABC1D23\nAntigo:   [A-Z]{3}[0-9]{4}              → ABC1234\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Validação em Node:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"function placaValida(placa: string): boolean {\n  return /^[A-Z]{3}[0-9][A-Z][0-9]{2}$/.test(placa) ||\n         /^[A-Z]{3}[0-9]{4}$/.test(placa);\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success","name":"Logging"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Logue sempre o campo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["erro"]}," (não apenas o status HTTP) para facilitar triagem. O código de erro identifica a causa exata sem precisar analisar a mensagem em texto livre."]}]}]},"headings":[{"value":"Erros","id":"erros","depth":1},{"value":"Códigos HTTP","id":"códigos-http","depth":2},{"value":"Catálogo de erros de aplicação","id":"catálogo-de-erros-de-aplicação","depth":2},{"value":"Erros 5xx","id":"erros-5xx","depth":2},{"value":"Validação de placa","id":"validação-de-placa","depth":2}],"frontmatter":{"title":"Erros — Parceiros Movvia","description":"Catálogo de códigos de erro, causas e ações recomendadas na API de Parceiros Movvia.","seo":{"title":"Erros"}},"lastModified":"2026-04-25T15:17:56.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/parceiros/guides/erros","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}