Quando algo dá errado, a resposta traz um código que diz o motivo. Na API, ele vem em error.code. No MCP, a sua IA recebe o mesmo motivo e costuma explicar o que aconteceu. Encontre o código abaixo e veja o que fazer.
A cotação voltou vazia
A cotação pode responder sem erro e mesmo assim sem nenhuma opção de frete. Nesse caso, a resposta traz um motivo:
- no_services_enabled: nenhum serviço dos Correios está ligado. No painel, na aba Frete, ligue pelo menos um em Serviços de entrega e salve.
- correios_auth_failed: os Correios recusaram os dados do seu contrato. Confira o usuário, o cartão de postagem e o código de acesso à API em Contrato dos Correios.
Cotação vazia não é frete grátis. Se a sua loja mostra o frete no checkout, não trate a falta de opções como frete zero.
Erros de chave
- missing_api_key ou invalid_api_key (401): a chave não foi enviada ou está errada.
- secret_key_required ou wrong_key_scope (403): a chave usada não pode fazer essa operação, como rastrear com a chave pública.
Veja chave pública e chave secreta, qual usar.
Erros de plano e de limite
- free_quota_exceeded (402): acabaram as chamadas do mês do plano Grátis para essa operação.
- subscription_required (402): a operação exige um plano ativo. Confira o seu plano na aba Plano.
- rate_limited (429): a loja passou do limite por minuto. Espere os segundos indicados e tente de novo.
Veja quais são os limites de uso e o que inclui o plano Grátis.
Erros na chamada
- invalid_destination_cep (400): o CEP de destino é inválido. Confira os 8 dígitos.
- invalid_json ou invalid_body (400): a chamada foi enviada com formato errado. Compare com o exemplo do portal de desenvolvedores.
- too_many_items ou too_many_codes (400): mais de 50 itens na cotação ou mais de 50 códigos no rastreio. Divida em chamadas menores.
- payload_too_large (413): a chamada passou de 32.000 bytes. Reduza o conteúdo enviado.
- merchant_not_found (404): a chave não está ligada a nenhuma loja. Copie a chave de novo do painel.
Os Correios não responderam
- quote_failed ou track_failed (502): o serviço dos Correios ficou indisponível naquele momento. Tente de novo em instantes. Se repetir, fale com o suporte.
Erros ao gerar etiqueta
- invalid_invoice_key: a chave da nota fiscal precisa ter exatamente 44 dígitos. Confira a chave na nota, sem completar dígitos.
- declaration_required: sem nota fiscal, a etiqueta precisa dos itens da declaração de conteúdo. Informe os itens do pacote.
- dimensions_required_no_box: faltam as medidas do pacote. Informe as medidas ou cadastre uma embalagem no painel, na aba Frete.
Se a etiqueta deu erro no meio do caminho, não gere de novo sem antes conferir, porque cada nova tentativa pode criar outra pré-postagem nos Correios.
Peça ajuda para a sua IA
Se você usa o meu ecommerce pelo MCP, peça à sua IA para diagnosticar o problema. Ela tem ferramentas próprias para isso, como o diagnóstico da cotação, do contrato e da etiqueta, e explica o que encontrou.
Os detalhes técnicos estão no portal de desenvolvedores.
Fale com o nosso suporte
Não encontrou o erro aqui ou o problema continua? Fale com a gente:
- E-mail: suporte@meuecommerce.com.br
- WhatsApp: +55 11 9 8865-0702
Atendemos de segunda a sexta-feira, exceto feriados, das 9h às 17h. Para agilizar, mande o código do erro e, se tiver, o momento em que ele aconteceu.