Erros, limites e consumo
Trate respostas de erro, respeite os limites e acompanhe o consumo da conta.
As respostas de erro contêm request_id e um objeto error, com code, message e, quando aplicável, details.
Use o status HTTP e error.code para decidir o tratamento. O texto da mensagem pode mudar. O cabeçalho X-Request-ID corresponde ao request_id do corpo.
Códigos de erro
| HTTP | error.code | Como tratar |
|---|---|---|
400 | https_required | Use HTTPS desde a primeira chamada. |
400 | invalid_json | Envie um objeto JSON válido. |
400 | invalid_query | Remova parâmetros de URL não permitidos; cotações recebem os dados no corpo JSON. |
401 | invalid_credentials | Confira alias, senha de API e token do mesmo conjunto. |
403 | account_not_eligible, forbidden | Verifique a situação da conta e os pré-requisitos de cadastro. |
404 | route_not_found | Confira o caminho completo da operação. |
404 | shipment_not_found | O envio não está disponível para essa conta. Confira o ID obtido na listagem. |
405 | method_not_allowed | Use o método indicado no cabeçalho Allow. |
409 | shipment_changed | A etiqueta mudou durante a leitura do rastreamento. Reinicie sem cursor. |
413 | payload_too_large | Reduza o corpo da requisição; o limite é 256 KiB. |
415 | unsupported_media_type | Envie cotações com Content-Type: application/json. |
422 | validation_error | Corrija os campos da cotação indicados em error.details.fields. |
422 | invalid_query | Corrija o parâmetro indicado em error.details.field. Se for cursor, reinicie a consulta sem ele. |
422 | sender_profile_required | Complete os dados do remetente em Configurações do perfil. |
429 | rate_limited | Aguarde os segundos indicados em Retry-After. |
503 | quote_unavailable | A cotação está temporariamente indisponível. Respeite Retry-After e a política de tentativas abaixo. |
503 | authentication_unavailable | Aguarde a recuperação da autenticação; não gere novas credenciais automaticamente. |
503 | rate_limit_unavailable | Aguarde a recuperação do controle de tráfego; respeite Retry-After quando presente. |
503 | api_unavailable, service_unavailable | Aguarde e tente novamente conforme a política abaixo; acione o suporte se persistir. |
Mantenha um tratamento geral por status HTTP para códigos ainda desconhecidos. Não dependa do texto de message.
Exemplos de erro
Credenciais inválidas, HTTP 401:
{
"request_id": "0123456789abcdef0123456789abcdef",
"error": {
"code": "invalid_credentials",
"message": "Credenciais de API invalidas."
}
}Campo de cotação inválido, HTTP 422. details.fields é uma lista de objetos com field e code:
{
"request_id": "0123456789abcdef0123456789abcdef",
"error": {
"code": "validation_error",
"message": "Revise os campos da cotacao.",
"details": {
"fields": [
{ "field": "weight_g", "code": "invalid_positive_integer" }
]
}
}
}Parâmetro de consulta inválido, HTTP 422. Neste caso, details.field é uma string:
{
"request_id": "0123456789abcdef0123456789abcdef",
"error": {
"code": "invalid_query",
"message": "Parâmetro de consulta inválido.",
"details": { "field": "limit" }
}
}Limite de chamadas atingido, HTTP 429. Por exemplo, o cabeçalho Retry-After: 30 pede uma espera de 30 segundos; o valor varia:
{
"request_id": "0123456789abcdef0123456789abcdef",
"error": {
"code": "rate_limited",
"message": "Limite de requisicoes excedido."
}
}Limites de requisições
Os limites iniciais por conta são:
| Operação | Limite |
|---|---|
| Cotações | 60 chamadas por minuto |
| Leituras de envios e rastreamento, somadas | 120 chamadas por minuto |
Os limites são compartilhados pelos sistemas que usam a conta. Rotacionar o token não reinicia a contagem. Chamadas autenticadas com erro de validação também entram no limite por minuto. Proteções gerais de tráfego podem limitar requisições; use o Retry-After recebido.
Timeouts e novas tentativas
Para consultas GET, repita chamadas que falharam por conexão, timeout, 429 ou 503 com um número limitado de tentativas. Respeite Retry-After quando presente; caso contrário, aumente progressivamente o intervalo e inclua uma pequena variação aleatória. Corrija os demais erros antes de reenviar, seguindo a tabela acima.
Para POST de cotação, cada nova execução pode gerar novo consumo. A API não oferece deduplicação por Idempotency-Key: repetir o mesmo corpo ou esse cabeçalho não evita a contabilização de uma nova cotação. Se a conexão cair ou o cliente atingir o timeout, a chamada anterior pode ter sido processada e contabilizada mesmo sem você receber a resposta. Evite retries transparentes nesse caso; só faça uma nova cotação quando aceitar esse possível consumo.
O processamento das transportadoras tem um orçamento de até 8 segundos. Configure o timeout total do cliente acima desse valor, com margem para rede e processamento da Veolog; esses 8 segundos não são uma garantia de duração total. Em 429 ou 503, respeite a espera indicada antes de decidir repetir a cotação.
Consumo do plano
O limite por minuto mede chamadas. O consumo de cotações segue o plano e pode contabilizar várias opções retornadas em uma chamada.
Uma opção contendo valores operacional e de checkout é contabilizada uma única vez. Frete grátis no checkout preserva a cotação operacional e seu consumo.
Não há taxa adicional de acesso à API nem sandbox público. Testes de cotação usam a conta real e o consumo normal do plano.
Suporte
Registre request_id, operação, horário e status. Remova os cabeçalhos User-Token e User-Secret-Key de logs e ferramentas de diagnóstico.
Abra o suporte da Veolog e envie o request_id. Não compartilhe senha ou token.
Updated about 1 month ago