Erros e limites
Respostas HTTP, falhas de negócio e como tentar novamente.
Erros REST
{
"error": {
"code": "invalid_api_key",
"message": "Chave de API inválida."
}
}actionUrl pode aparecer dentro de error quando o lojista precisa concluir uma ação.
| Status | Exemplos de código | Ação |
|---|---|---|
| 400 | invalid_json, invalid_body, invalid_destination_cep, too_many_items, too_many_codes | Corrija a requisição |
| 401 | missing_api_key, invalid_api_key | Revise o header e a credencial |
| 403 | secret_key_required, wrong_key_scope | Use a credencial com o escopo correto |
| 402 | subscription_required, free_quota_exceeded | Confira o acesso ao plano e a actionUrl; free_quota_exceeded traz Retry-After até a virada do mês |
| 404 | merchant_not_found | Confira a loja vinculada à credencial |
| 405 | method_not_allowed | Use o método documentado |
| 413 | payload_too_large | Reduza o corpo JSON |
| 429 | rate_limited | Aguarde os segundos indicados em Retry-After |
| 502 | quote_failed, track_failed | Trate a indisponibilidade temporária |
Respostas vazias
200 não garante cotação disponível. Examine rates, reason e actionUrl. Exemplos incluem no_services_enabled e correios_auth_failed, que pedem revisão da configuração da loja.
No MCP, examine structuredContent.reason e o texto em content, mesmo quando a chamada ao protocolo foi concluída.
Validação de etiquetas no MCP
invalid_invoice_key indica que invoiceKey foi informada sem exatamente 44 dígitos após remover espaços e separadores. Peça a chave completa da NF-e; o MCP rejeita a solicitação antes de emitir nos Correios. Não complete dígitos ausentes nem troque automaticamente para DC-e.
declaration_required indica que faltam itens em declaredItems quando invoiceKey não foi informada. Nesse caso, a emissão também é bloqueada antes da chamada aos Correios. Consulte o guia de etiquetas.
Limites da implementação REST
| Limite | Valor |
|---|---|
| Itens por cotação | Até 50 linhas de itens |
| Códigos por rastreamento | Até 50 códigos |
| Corpo JSON | Até 32.000 bytes |
Limites de uso por loja
Os limites valem por loja e por operação, e são os mesmos na API REST e no Meu Ecommerce MCP.
| Operação | Por minuto |
|---|---|
Cotação (/v1/rates, get_shipping_rates) | 60 |
Rastreio (/v1/tracking, track_shipment) | 30 |
Download de etiqueta (get_label_pdf) | 30 |
Emissão de etiqueta (generate_label) | 20 |
Acima do limite por minuto, a resposta é rate_limited (REST 429, com Retry-After). A janela é o minuto do relógio em UTC, não os últimos 60 segundos.
Loja sem plano ativo está no plano Grátis e pode fazer até 10 chamadas por mês de cada operação. Depois disso, a resposta é free_quota_exceeded (REST 402), com actionUrl para assinar e Retry-After até o início do próximo mês em UTC. Lojas com plano ativo não têm limite mensal.
Planos
| Plano | Chamadas por mês, por operação | Embalagens usadas no cálculo |
|---|---|---|
| Grátis (sem assinatura) | 10 | 1 |
| Pro | Sem limite | 1 |
| Avançado | Sem limite | Até 5 |
Todos os planos têm os limites por minuto acima. Embalagens cadastradas além do limite do plano ficam salvas, mas não entram na cotação. Assinatura e planos ficam no painel.
No MCP, os mesmos motivos aparecem em structuredContent.reason, com retryAfterSeconds.
Os valores descrevem a configuração atual da implementação, não uma garantia de capacidade. Sua integração deve sempre tratar 429 e 402.
Novas tentativas
Para cotação e rastreio, use espera progressiva com variação e um número máximo de tentativas em falhas transitórias. Não repita automaticamente erros de configuração ou autenticação.
requestId pode ajudar a correlacionar uma cotação. A implementação não documenta garantia de deduplicação por esse campo.
Na emissão de etiquetas, uma nova tentativa pode criar outra pré-postagem. Se já recebeu um identificador, use get_label_pdf para recuperar o PDF. Sem ele, consulte a tentativa com diagnose_label_issue.