Integração

Catálogo de erros

Cada código tem causa e como corrigir. Os links das respostas de erro e do registro de chamadas apontam direto para o código aqui.

Formato da resposta de erro#

json

{
  "error": {
    "type": "VALIDATION_ERROR",
    "message": "Dados inválidos",
    "description": "Confira os campos indicados.",
    "fields": [
      { "campo": "quantidadeImagens", "codigo": "VALOR_NAO_PERMITIDO", "mensagem": "Use 3, 6 ou 10 imagens." }
    ],
    "documentation": "https://docs.sellume.com.br/erros#VALIDATION_ERROR"
  }
}

Campo	O que é
`type`	código estável, em inglês maiúsculo. Use este campo no seu código, nunca o texto.
`message`	mensagem curta em português
`description`	explicação em português do que aconteceu nesta chamada
`fields`	campos com problema (`campo`, `codigo`, `mensagem`). Em `422`, as pendências da conferência.
`documentation`	link para o código nesta página

Toda resposta traz X-Request-Id. Com ele, o registro de chamadas mostra a causa, o como corrigir e o corpo enviado e recebido (mascarados). Estes textos são os mesmos de GET/integracao/erros.

Erros da API#

Valor de error.type, com o status HTTP.

ACCOUNT_PAUSEDHTTP 403#

Conta pausada

Causa: Subconta pausada ou encerrada.
Como corrigir: Reative com PATCH/contas/{contaId} (situacao: ativa).

CONFLICTHTTP 409#

Conflito

Causa: O estado atual não permite a ação ou há duplicidade (codigoExterno).
Como corrigir: Leia o recurso atual; em duplicidade, use o id existente informado em fields.

FORBIDDENHTTP 403#

Sem permissão

Causa: A credencial não tem permissão para esta ação ou conta.
Como corrigir: Use uma chave com o escopo e a conta necessários.

IDEMPOTENCY_KEY_REQUIREDHTTP 400#

Idempotency-Key obrigatório

Causa: POST que gasta crédito sem o cabeçalho Idempotency-Key.
Como corrigir: Envie um UUID novo por pedido no cabeçalho Idempotency-Key.

IDEMPOTENCY_KEY_REUSEDHTTP 409#

Chave de idempotência já usada

Causa: A mesma Idempotency-Key foi usada com outro corpo.
Como corrigir: Gere uma chave nova para cada pedido diferente; repita a mesma só para o mesmo pedido.

INSUFFICIENT_CREDITSHTTP 402#

Créditos insuficientes

Causa: Saldo insuficiente: a cota do mês (créditos do plano, que também são o teto) acabou e não há crédito avulso guardado, ou o saldo pré-pago não cobre o pedido. Nada foi cobrado.
Como corrigir: Compre um pacote avulso (POST/recargas ou portal; não vence) ou espere o próximo ciclo. A subida de plano, pedida no portal, vale a partir do próximo ciclo. Veja GET/saldo, GET/cota-do-mes e GET/plano.

INTEGRATION_STEPS_PENDINGHTTP 409#

Etapas da integração pendentes

Causa: Pedido de produção com etapas pendentes.
Como corrigir: Veja GET/integracao/status e conclua as etapas.

INTEGRATOR_PAUSEDHTTP 403#

Integração pausada

Causa: Integrador pausado (atraso ou decisão administrativa).
Como corrigir: Regularize a fatura ou fale com o suporte pelo portal.

INTERNAL_ERRORHTTP 500#

Erro interno

Causa: Erro do nosso lado.
Como corrigir: Tente de novo com a mesma Idempotency-Key; se repetir, informe o X-Request-Id ao suporte.

MEDIA_DOWNLOAD_FAILEDHTTP 422#

Fotos não puderam ser baixadas

Causa: Nenhuma foto pôde ser baixada.
Como corrigir: Publique as fotos em HTTPS público, sem login e sem bloqueio por IP.

ORIGIN_NOT_ALLOWEDHTTP 403#

Origem não autorizada

Causa: Origem do componente embutido fora dos sites autorizados.
Como corrigir: Cadastre a origem exata (esquema + domínio + porta) no portal.

PAYLOAD_TOO_LARGEHTTP 413#

Conteúdo grande demais

Causa: Corpo ou foto acima do limite.
Como corrigir: Até 20 fotos de até 15 MB; corpo até 1 MB.

PRODUCT_NOT_VERIFIEDHTTP 422#

Produto ainda não conferido

Causa: A versão atual do produto não tem conferência concluída.
Como corrigir: Aguarde a conferência ou chame POST/produtos/{produtoId}/conferencia.

PRODUCT_REQUIREMENTS_NOT_METHTTP 422#

O produto não atende aos requisitos mínimos

Causa: A conferência reprovou o tipo pedido (ou a quantidade passa do máximo sustentado).
Como corrigir: Corrija as pendências de fields na ficha, envie de novo e espere a nova conferência.

QUOTA_LIMIT_REACHEDHTTP 402#

Teto de créditos da sessão atingido

Causa: Teto de gastos da sessão embutida atingido.
Como corrigir: Crie uma sessão com limiteCreditos maior.

RESOURCE_NOT_FOUNDHTTP 404#

Não encontrado

Causa: Id inexistente, de outro integrador ou de outro ambiente.
Como corrigir: Confira o id e se ele pertence a este integrador e a este ambiente (teste ou produção).

SERVICE_UNAVAILABLEHTTP 503#

Serviço indisponível

Causa: Falha passageira do serviço ao atender o pedido. Não é falta de vaga: pedidos sem vaga entram na fila com posição e tempo estimado.
Como corrigir: Repita o mesmo pedido com a mesma Idempotency-Key depois do Retry-After; nada foi cobrado.

TOO_MANY_REQUESTSHTTP 429#

Muitas requisições

Causa: Limite por minuto atingido.
Como corrigir: Espere os segundos de Retry-After e distribua as chamadas.

UNAUTHORIZEDHTTP 401#

Acesso não autorizado

Causa: Chave ausente, inválida, revogada ou expirada.
Como corrigir: Envie Authorization: Bearer <chave>; se a chave foi revogada, peça uma nova.

VALIDATION_ERRORHTTP 400#

Dados inválidos

Causa: Campo inválido ou ausente (veja fields).
Como corrigir: Corrija os campos listados em fields e envie de novo.

Erros dentro de uma geração#

Uma geração aceita (202) pode terminar com situacao: falhou. O motivo vem em erro.type da geração (GET/geracoes/{geracaoId} e aviso geracao.falhou), e os créditos voltam:

`erro.type`	Quer dizer
`GENERATION_FAILED`	nada foi entregue; créditos devolvidos
`VIDEO_SPEECH_NOT_APPROVED`	nenhuma opção de fala passou nas travas de qualidade; nada foi renderizado e os créditos voltaram (Vídeos)

Pendências da conferência#

Códigos de resultados[].pendencias[] da conferência e de fields do 422. bloqueio reprova o tipo; fraco aprova, mas a qualidade cai; por foto tira a foto (vira bloqueio só se faltar foto).

CARACTERISTICAS_AUSENTESbloqueio#

Nenhuma característica útil

Causa: Sem atributo útil (código, SKU, EAN não contam).
Como corrigir: Envie atributos com nome e valor (material, medida, potência, cor…).

CINEPREMIUM_FOTOS_INSUFICIENTESbloqueio#

Fotos insuficientes para o CinePremium

Causa: Menos de 3 fotos aprovadas.
Como corrigir: Envie 3+ fotos do produto de lados diferentes.

CONFERENCIA_FALHOUbloqueio#

A conferência não terminou

Causa: Erro técnico na conferência.
Como corrigir: Chame POST/produtos/{produtoId}/conferencia de novo.

DESCRICAO_CURTAbloqueio#

Descrição curta

Causa: Descrição com menos de 40 caracteres.
Como corrigir: Descreva o produto (o que é, para que serve, diferenciais); recomendado 300+.

FOTO_AMBIENTADApor foto#

Foto ambientada

Causa: Produto num ambiente real.
Como corrigir: Envie 2+ fotos de fundo liso; a ambientada sai do vídeo.

FOTO_AUSENTEbloqueio#

Nenhuma foto aprovada

Causa: Nenhuma foto passou nos requisitos.
Como corrigir: Envie pelo menos 1 foto do produto que passe nos requisitos.

FOTO_COM_CRIANCApor foto#

Foto com criança

Causa: Criança ou idade incerta na foto.
Como corrigir: Remova; fotos com criança nunca são usadas.

FOTO_COM_PESSOApor foto#

Foto com pessoa

Causa: Pessoa visível.
Como corrigir: Prefira fotos só do produto; a foto com pessoa sai do vídeo.

FOTO_DOWNLOAD_FALHOUpor foto#

A foto não abriu

Causa: A foto não abriu (404, login, bloqueio, tempo ou endereço interno).
Como corrigir: Publique em HTTPS público e confira o link.

FOTO_DUPLICADApor foto#

Foto repetida

Causa: A mesma imagem já foi enviada.
Como corrigir: Remova a repetida.

FOTO_EMBALAGEMpor foto#

Foto com embalagem

Causa: Produto dentro da caixa.
Como corrigir: Envie fotos do produto fora da embalagem.

FOTO_FORMATO_INVALIDOpor foto#

Formato de foto inválido

Causa: Não é JPEG, PNG ou WebP (pelos bytes).
Como corrigir: Converta para JPEG, PNG ou WebP.

FOTO_INFOGRAFICOpor foto#

Foto tipo infográfico

Causa: Layout com textos/ícones domina o produto.
Como corrigir: Envie a foto limpa do produto.

FOTO_OUTRA_VARIANTEpor foto#

Foto com outra variante

Causa: Mostra outra cor/modelo ou unidades a mais.
Como corrigir: Envie só fotos da variante anunciada.

FOTO_PRINCIPAL_NAO_E_PRODUTO_LIMPObloqueio#

A foto principal não é do produto limpo

Causa: A principal tem pessoa, ambiente, embalagem, infográfico ou outra variante.
Como corrigir: Marque como principal uma foto do produto sozinho, fora da caixa, em fundo liso.

FOTO_PROPORCAO_EXTREMAfraco#

Proporção extrema

Causa: Proporção fora de 0,4–2,5.
Como corrigir: Prefira fotos mais quadradas; no vídeo ela entra com borda branca.

FOTO_RESOLUCAO_BAIXApor foto#

Resolução baixa

Causa: Lado menor abaixo de 800 px.
Como corrigir: Envie foto com pelo menos 800 px (ideal 1200).

FOTO_SEM_PESSOA_AUSENTEbloqueio#

Nenhuma foto só do produto

Causa: Todas as fotos têm pessoa.
Como corrigir: Envie pelo menos 1 foto só do produto.

FOTO_TAMANHO_INVALIDOpor foto#

Tamanho de foto inválido

Causa: Menor que 1 KB ou maior que 15 MB.
Como corrigir: Envie a foto original, até 15 MB.

FOTOS_FUNDO_LISO_INSUFICIENTESfraco#

Poucas fotos de fundo liso

Causa: Menos de 2 fotos de fundo liso.
Como corrigir: Envie 2+ fotos em fundo liso.

GALERIA_ABAIXO_DO_MINIMObloqueio#

A ficha não sustenta 3 imagens

Causa: Os dados não sustentam 3 imagens.
Como corrigir: Envie mais características, avaliações/perguntas e garantia.

GALERIA_QUANTIDADE_ACIMA_DO_SUPORTADOfraco#

Quantidade acima do sustentado

Causa: Pediu mais imagens que o máximo sustentado.
Como corrigir: Peça até quantidadeMaximaImagens ou enriqueça a ficha.

MARCA_AUSENTEfraco#

Sem marca

Causa: Marca não informada.
Como corrigir: Envie marca.

NOME_AUSENTEbloqueio#

Nome do produto ausente ou curto

Causa: Sem nome ou com menos de 3 caracteres.
Como corrigir: Envie nome com o nome comercial do produto.

OFERTA_QUANTIDADE_AMBIGUAbloqueio#

Quantidade da oferta ambígua

Causa: Não dá para saber quantas unidades vêm.
Como corrigir: Envie composicaoOferta com cada item e a quantidade.

POUCAS_CARACTERISTICASfraco#

Poucas características

Causa: Menos de 3 características.
Como corrigir: Envie 3+ atributos úteis.

POUCOS_ANGULOSfraco#

Poucos ângulos

Causa: Menos de 3 fotos.
Como corrigir: Envie fotos de outros lados.

ROUPA_FOTOS_SEM_PESSOA_INSUFICIENTESbloqueio#

Roupa sem fotos da peça sozinha

Causa: Roupa/calçado com menos de 2 fotos da peça sem pessoa.
Como corrigir: Envie 2+ fotos em cabide, manequim ou estendida.

SEM_AVALIACOES_OU_PERGUNTASfraco#

Sem avaliações nem perguntas

Causa: Sem avaliações e sem perguntas.
Como corrigir: Envie avaliações e perguntas reais (sem dados pessoais).

SEM_GARANTIAfraco#

Sem garantia

Causa: Garantia não informada.
Como corrigir: Envie garantia (ex. 12 meses contra defeitos).

VIDEO_NOTA_BAIXAbloqueio#

Nota de vídeo abaixo de 5

Causa: Nota de vídeo abaixo do mínimo.
Como corrigir: Some pontos: 3+ fotos, 3+ características, avaliações ou perguntas, garantia.

Falhas de entrega de aviso#

Valor de motivoFalha nas entregas de aviso (GET/avisos/{avisoId}/entregas) e no teste de assinatura.

assinatura_nao_conferidafalha de entrega#

Assinatura não conferida

Causa: No teste, aceitou assinatura errada ou carimbo antigo.
Como corrigir: Confira X-Sellume-Signature com o segredo whsec_ em tempo constante e recuse carimbo com mais de 5 min.

conexao_recusadafalha de entrega#

Conexão recusada

Causa: Não deu para conectar.
Como corrigir: Confira o endereço, o certificado HTTPS e o firewall.

dnsfalha de entrega#

Falha de DNS

Causa: O endereço não resolveu.
Como corrigir: Confira o domínio do endereço.

endereco_bloqueadofalha de entrega#

Endereço bloqueado

Causa: O endereço aponta para rede interna.
Como corrigir: Use um endereço HTTPS público.

status_httpfalha de entrega#

Status HTTP fora de 2XX

Causa: Respondeu fora de 2XX.
Como corrigir: Veja o status em ultimoStatusHttp e o log do seu endpoint.

tempo_esgotadofalha de entrega#

Tempo esgotado

Causa: Sem resposta em 5 s.
Como corrigir: Responda 2XX logo e processe depois (fila do seu lado).

tlsfalha de entrega#

Falha de TLS

Causa: Certificado inválido.
Como corrigir: Use um certificado HTTPS válido.

OAuth: endpoint de token#

Respostas de erro de POST/oauth/token no formato RFC 6749: {"error": "…", "error_description": "…"}. Fluxo completo em Autenticação.

invalid_requestHTTP 400#

Causa: Falta um parâmetro obrigatório ou algum parâmetro veio repetido.
Como corrigir: Confira o corpo: grant_type e os campos do tipo de concessão (code, redirect_uri, code_verifier e client_id; ou refresh_token), cada um uma vez só.

invalid_clientHTTP 401#

Causa: client_id ou client_secret errado, ou o app está desativado.
Como corrigir: Confira as credenciais do app no portal (Apps OAuth). Se o segredo foi trocado, use o novo: o anterior deixa de valer na hora.

invalid_grantHTTP 400#

Causa: Código inválido, vencido ou já usado; redirect_uri diferente do usado na autorização; code_verifier que não confere com o code_challenge; ou refresh token inválido, vencido ou reusado.
Como corrigir: Refaça a autorização com o vendedor. O código vale 60 segundos e uma vez só; o refresh token é trocado a cada uso.

unauthorized_clientHTTP 400#

Causa: O app não pode usar este tipo de concessão.
Como corrigir: Confira no portal o tipo e o ambiente do app e use authorization_code ou refresh_token.

unsupported_grant_typeHTTP 400#

Causa: grant_type desconhecido.
Como corrigir: Use grant_type=authorization_code ou grant_type=refresh_token.

invalid_scopeHTTP 400#

Causa: Escopo fora dos permitidos do app ou maior que o autorizado pelo vendedor.
Como corrigir: Peça só escopos permitidos no cadastro do app. Na renovação, peça o mesmo escopo ou um menor.

temporarily_unavailableHTTP 429#

Causa: Muitas chamadas ao endpoint de token pelo mesmo app.
Como corrigir: Espere os segundos do cabeçalho Retry-After. Reaproveite o access token até perto de vencer, em vez de pedir um novo a cada chamada.