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 | Confira o acesso ao plano e a actionUrl |
| 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 antes de tentar novamente |
| 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.
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 |
| Limitador configurado no servidor | 60 chamadas por 60 segundos, por loja e rota |
O limitador atual é mantido em memória por instância de servidor. O valor descreve a configuração da implementação, não uma garantia de quota global ou de capacidade. Sua integração deve sempre tratar 429.
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.