Erros
O que cada código significa, o que causa e o que fazer — em ordem de frequência.
Cada status diz de quem é o problema. Ler o corpo da resposta economiza horas de tentativa e erro.
Resumo rápido
| Status | De quem é o problema | Ação |
|---|---|---|
401 |
Autenticação ou conta | Gerar/usar token válido; conferir status da conta |
404 |
Registro inexistente | Conferir o id no caminho |
405 |
Método errado | Usar o verbo documentado no endpoint |
422 |
Validação de campos | Ler data.<campo> e corrigir |
429 |
Limite da sua infraestrutura | Backoff exponencial |
500 |
Interno da Hubiss | Tentar depois; já é notificado |
400 — requisição inválida
Não é usado pela API para erros de campo: JSON quebrado, tipo errado ou campo ausente caem em 422. Se receber 400, quase sempre é um proxy ou gateway na frente da API recusando a requisição.
Como corrigir: valide o JSON antes de enviar e compare com o exemplo da página do endpoint.
405 — método não permitido
A rota existe, mas não aceita aquele verbo. Por exemplo, POST /v1/orders não existe: pedidos são criados pelo marketplace.
Como corrigir: use o verbo listado na página do endpoint (GET, POST, PUT, PATCH ou DELETE).
401 — não autorizado
Token ausente, inválido ou expirado retorna 401 com "error": "Unauthorized". Com token válido, o middleware também responde 401 quando há um problema no estado da conta:
| Causa | Mensagem em error |
|---|---|
| Cadastro bloqueado | Seu cadastro foi bloqueado no sistema. Caso ache que foi um engano, entre em contato conosco. |
| Cadastro incompleto | Seu cadastro está incompleto. |
| Sem assinatura ativa | Você não assinou ou possui um plano ativo. |
No POST /v1/stores/{storeId}/products, o 401 também aparece quando a loja atingiu o limite de produtos permitido antes da aprovação para integração.
Como corrigir: gere um novo token no painel se a autenticação falhar. Para mensagens de conta, regularize o cadastro ou plano conforme indicado. Lembre: gerar um token invalida o anterior na hora.
404 — não encontrado
O registro do caminho não existe ou pertence a outra conta. Muito comum com storeId de outra conta.
{
"error": "Resource 123 not found"
}
Como corrigir: use o id retornado no cadastro. Se você copiou um id de exemplo da documentação, ele não existe.
422 — falha de validação
O caso mais frequente em integrações novas. O corpo lista os campos recusados com a razão:
{
"success": false,
"message": "Validation errors",
"data": {
"status": [
"Cannot change status now, check documentation"
]
}
}
Campo em data | O que geralmente significa |
|---|---|
status | Mudança de status fora de ordem (pedidos) |
categories / categories.0.id | Categoria obrigatória ausente, de outra loja ou inexistente |
sku | SKU repetido na conta ou vazio |
variations / variations.0.sku | Variações incompletas ou SKU de variação repetido |
language_code | Idioma não suportado ou fora dos idiomas da loja |
country | Código de país inválido (ex.: BR) |
email / customer.* / shipment.* | Alteração bloqueada pelo status atual do pedido |
url / file | URL de imagem inválida, arquivo grande demais ou extensão não suportada |
number / access_key | Dados da nota fiscal ausentes ou fora do formato |
Como corrigir: ajuste o campo indicado e reenvie uma vez. Repetir o mesmo payload só gera mais 422.
429 — muitas requisições
A API não aplica limite por token hoje; o 429 vem da sua infraestrutura (proxy, CDN ou gateway) quando ela impõe um teto. Veja Limitação para a política de espera.
500 e 501 — erro interno
Falha inesperada no servidor. A Hubiss é notificada automaticamente.
Como fazer: aguarde alguns segundos e repita com backoff. Se persistir por mais de alguns minutos, abra um chamado informando horário, endpoint e o id envolvido.
Estratégia recomendada de tratamento
401 -> alerta para o time; não repete automaticamente
404 -> registra e segue (registro pode ter sido excluído)
422 -> registra por campo; NÃO repete o mesmo payload
429 -> espera com backoff e repete
5xx -> espera com backoff e repete (máx. 5 tentativas)
429 e 5xx. 400, 401, 404, 405 e 422 exigem correção — repetir piora.