Erros e limites

Quando uma chamada falha, a API responde com um status HTTP de erro e um corpo JSON explicando o motivo. Esta página mostra os formatos possíveis, as mensagens que mais aparecem e o que fazer em cada caso.

Formatos de erro

Erro de validação

Campos ausentes ou inválidos voltam com status 400 e o objeto errors, com a lista de problemas de cada campo:

{
  "message": "Ocorreu um ou mais erros.",
  "errors": {
    "to.postal_code": ["(to.postal_code) é inválido."]
  }
}

Use as chaves de errors para destacar o campo certo na sua tela ou no seu log. A mensagem geral (message) é sempre a mesma; o detalhe está dentro de errors.

Erro de regra de negócio ou autenticação

Token inválido, saldo insuficiente, pedido que não pode mais ser cancelado e situações parecidas voltam com message e error, que trazem o mesmo texto:

{
  "message": "Sem saldo na carteira! Utilize o app para recarregar a carteira ou pagar a etiqueta com cartão de crédito.",
  "error": "Sem saldo na carteira! Utilize o app para recarregar a carteira ou pagar a etiqueta com cartão de crédito."
}

Erro no OAuth

O endpoint de troca de código por token segue o formato do OAuth 2.0, com error, http_status, error_description e message. A lista completa está no guia do fluxo OAuth 2.0.

Não dependa do texto da mensagem

As mensagens vêm em português, mas algumas poucas ainda chegam em inglês (como user.phone is required.) e os textos podem mudar. Trate o erro pelo status HTTP e pelo campo em errors, e não pelo texto exato da mensagem.

Status HTTP

Status	Quando acontece	O que fazer
`400`	Campo obrigatório ausente, valor inválido ou regra de validação não atendida.	Corrija a requisição conforme `errors`. Não adianta repetir igual.
`401`	Token ausente, inválido, revogado ou de outro ambiente.	Confira o header `Authorization: Bearer {token}` e se o token é do ambiente certo.
`403`	A operação não é permitida para essa conta.	Fale com o suporte se achar que deveria ter acesso.
`404`	Webhook App inexistente ou de outra conta. Pedidos inexistentes não voltam `404`: a consulta e o cancelamento respondem `400`, e o checkout responde `500`.	Confira o ID enviado.
`409`	A ação conflita com o estado atual: pedido já pago, pedido que não pode mais ser cancelado, saldo insuficiente, limite de etiquetas atingido.	Leia a mensagem e resolva a pendência antes de tentar de novo.
`429`	Muitas requisições em pouco tempo.	Espere alguns segundos e tente de novo, com intervalo crescente entre as tentativas.
`500`, `503`, `504`	Falha temporária do nosso lado ou de uma transportadora.	Tente de novo com intervalo crescente. Se persistir, fale com a gente informando o horário e o endpoint.

Mensagens mais comuns

Status	Mensagem	O que significa
`401`	`Token inválida!`	O token não existe, foi revogado (a integração foi excluída no painel) ou é de outro ambiente. Gere um novo token ou refaça o OAuth.
`401`	`Não autenticado!`	O header `Authorization` veio sem o token depois de `Bearer`.
`400`	`user.phone is required.`	A conta SuperFrete não tem celular cadastrado. Cadastre no perfil do painel e tente de novo.
`400`	`Cadastro incompleto. Por favor, finalizar o cadastro para prosseguir`	O cadastro da conta está incompleto. Finalize no painel.
`400`	`Campo CPF/CNPJ do destinatário é obrigatório para seguir com geração da etiqueta.`	Envie `to.document` com o CPF ou CNPJ do destinatário.
`400`	`O telefone do destinatário deve ter 10 ou 11 dígitos`	Envie `to.phone` só com números, com DDD.
`400`	`Nota fiscal habilitada apenas para Correios.`	Para Jadlog, Loggi e J&T, use declaração de conteúdo (envie `products`).
`400`	`Serviço Jadlog não está habilitado para este usuário.`	A transportadora está desativada nas configurações do token. O mesmo vale para Loggi e J&T. Veja Regras por transportadora.
`400`	`Essa modalidade do Correios não está habilitada.`	O serviço dos Correios pedido não está disponível para a conta.
`409`	`Sem saldo na carteira! …`	O saldo da carteira não cobre a etiqueta. Recarregue e chame o checkout de novo.
`409`	`Não foi possível realizar a compra pois o limite de etiquetas disponível para esta conta foi atingido. …`	A conta atingiu o limite de etiquetas aguardando postagem. Veja abaixo.
`409`	`Pedido já comprado.`	A etiqueta já foi paga. Não chame o checkout de novo.
`409`	`Este pedido está cancelado e não pode ser pago. …`	A etiqueta foi cancelada. Crie uma nova.
`409`	`Esse pedido não pode mais ser cancelado!`	A etiqueta já foi postada ou concluída e não pode mais ser cancelada.
`404`	`Aplicação Webhook não encontrada ou permissões insuficientes para acesso`	O ID do Webhook App não existe ou é de outra conta.

Limites

Etiquetas aguardando postagem

Cada conta tem um limite de etiquetas pagas que ainda não foram postadas. Quando ele é atingido, o checkout responde 409 com a mensagem "Não foi possível realizar a compra pois o limite de etiquetas disponível para esta conta foi atingido…".

Consulte a situação em GET /api/v0/user, no objeto limits:

{
  "limits": {
    "shipments": 48,
    "shipments_available": 2
  }
}

shipments: etiquetas aguardando postagem.
shipments_available: quantas ainda cabem no limite.

Para liberar espaço, poste os pacotes pendentes ou cancele as etiquetas que não vai usar. Se o volume da sua operação precisa de um limite maior, escreva para integracao@superfrete.com.

Requisições

Não há um limite de requisições por minuto publicado. Mesmo assim, evite rajadas desnecessárias:

Guarde a cotação do carrinho por alguns minutos em vez de cotar de novo a cada clique.
Use webhooks para saber quando o status muda, em vez de consultar o pedido em loop.
Tente de novo com intervalo crescente (1 s, 2 s, 4 s...) quando receber 429 ou 5xx.

Outros limites

O quê	Limite
Resposta da sua URL de webhook	10 segundos para responder `2xx`
Validade do `code` do OAuth	10 minutos, uso único
Validade do token de acesso	Não expira. Deixa de valer se a integração for excluída no painel
Peso, medidas e seguro dos Correios	Devolvidos por `GET /api/v0/services/info`
Jadlog, Loggi e J&T	Veja Regras por transportadora

Quando falar com a gente

Se o erro não estiver aqui ou continuar depois da correção, escreva para integracao@superfrete.com com:

o endpoint e o ambiente (sandbox ou produção);
o horário aproximado da chamada;
o corpo da requisição, sem o token;
a resposta completa que você recebeu.

Ou fale com a gente pelo chat.

Formatos de erro​

Erro de validação​

Erro de regra de negócio ou autenticação​

Erro no OAuth​

Status HTTP​

Mensagens mais comuns​

Limites​

Etiquetas aguardando postagem​

Requisições​

Outros limites​

Quando falar com a gente​