API Docs v1 api.hubiss.com.br

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.

JSONjson
{
    "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:

JSONjson
{
    "success": false,
    "message": "Validation errors",
    "data": {
        "status": [
            "Cannot change status now, check documentation"
        ]
    }
}
Campo em dataO que geralmente significa
statusMudança de status fora de ordem (pedidos)
categories / categories.0.idCategoria obrigatória ausente, de outra loja ou inexistente
skuSKU repetido na conta ou vazio
variations / variations.0.skuVariações incompletas ou SKU de variação repetido
language_codeIdioma não suportado ou fora dos idiomas da loja
countryCódigo de país inválido (ex.: BR)
email / customer.* / shipment.*Alteração bloqueada pelo status atual do pedido
url / fileURL de imagem inválida, arquivo grande demais ou extensão não suportada
number / access_keyDados 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

Saída esperadatext
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)
Regra prática
Só repita automaticamente 429 e 5xx. 400, 401, 404, 405 e 422 exigem correção — repetir piora.
Próximo passo
Siga para o Fluxo completo de integração e coloque a integração em ordem.