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

HTTPerror.codeComo tratar
400https_requiredUse HTTPS desde a primeira chamada.
400invalid_jsonEnvie um objeto JSON válido.
400invalid_queryRemova parâmetros de URL não permitidos; cotações recebem os dados no corpo JSON.
401invalid_credentialsConfira alias, senha de API e token do mesmo conjunto.
403account_not_eligible, forbiddenVerifique a situação da conta e os pré-requisitos de cadastro.
404route_not_foundConfira o caminho completo da operação.
404shipment_not_foundO envio não está disponível para essa conta. Confira o ID obtido na listagem.
405method_not_allowedUse o método indicado no cabeçalho Allow.
409shipment_changedA etiqueta mudou durante a leitura do rastreamento. Reinicie sem cursor.
413payload_too_largeReduza o corpo da requisição; o limite é 256 KiB.
415unsupported_media_typeEnvie cotações com Content-Type: application/json.
422validation_errorCorrija os campos da cotação indicados em error.details.fields.
422invalid_queryCorrija o parâmetro indicado em error.details.field. Se for cursor, reinicie a consulta sem ele.
422sender_profile_requiredComplete os dados do remetente em Configurações do perfil.
429rate_limitedAguarde os segundos indicados em Retry-After.
503quote_unavailableA cotação está temporariamente indisponível. Respeite Retry-After e a política de tentativas abaixo.
503authentication_unavailableAguarde a recuperação da autenticação; não gere novas credenciais automaticamente.
503rate_limit_unavailableAguarde a recuperação do controle de tráfego; respeite Retry-After quando presente.
503api_unavailable, service_unavailableAguarde 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çãoLimite
Cotações60 chamadas por minuto
Leituras de envios e rastreamento, somadas120 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.


Did this page help you?