Erros
Erros comuns do Listano Control MCP e orientações de recuperação.
As ferramentas do Listano Control MCP podem retornar erros de autenticação, permissões, validação, verificações de prontidão ou falhas de pedido ao servidor.
O padrão de recuperação mais seguro é:
- inspeccionar o erro
- chamar
whoamise as permissões não forem claras - chamar
get-offeringse o estado actual do rascunho não for claro - corrigir apenas os dados inválidos ou em falta
- chamar
check-offering-publish-readinessnovamente antes de publicar
Erros de permissão
Um erro de permissão significa que a integração autenticada não tem o âmbito necessário.
| Operação | Âmbito necessário |
|---|---|
| listar/ler/verificar | catalog:read |
| criar/actualizar/traduzir/descartar | catalog:write |
| publicar/descontinuar | catalog:publish |
Recuperação:
- chame
whoami - confirme os âmbitos concedidos
- solicite que o âmbito em falta seja concedido
Erros de não encontrado
Uma oferta pode não ser encontrada quando:
- o
offeringIdestá errado - a oferta pertence a outra empresa
- a integração está autenticada para uma empresa diferente
Recuperação:
- chame
list-offeringscom um título, SKU ou outro identificador conhecido - confirme a oferta seleccionada antes de a modificar
Erros de validação
Os erros de validação geralmente significam que a forma do input ou o valor de um campo é inválido.
Causas comuns:
| Causa | Correcção |
|---|---|
category_id sem category_label | Forneça ambos os campos. |
| Código de idioma inválido | Use get-supported-languages. |
| Idioma principal incluído nas traduções | Remova o idioma principal do payload de tradução. |
| Código de unidade inválido | Use um código de unidade válido de 3 caracteres. |
Atributo com unit mas valor não numérico | Use um valor numérico. |
Atributo com valueLabel mas valor não string | Use um valor string. |
Tentativa de alterar kind ou language | Descarte o rascunho e crie uma nova oferta. |
Erros de prontidão para publicação
check-offering-publish-readiness retorna:
{
offeringId: string
publishable: boolean
errors: unknown[]
}Quando publishable for false, não chame publish-offering.
Problemas de prontidão comuns:
- título, descrição ou unidade de medida em falta no idioma principal
- traduções em falta para idiomas não principais suportados
- etiquetas de categoria traduzidas em falta
- traduções de atributos em falta
- combinação inválida de valor/unidade de atributo
- descrições de atributos traduzidas ou etiquetas de valor em falta
Recuperação:
- corrija os erros retornados
- chame
check-offering-publish-readinessnovamente - publique apenas quando
publishablefortrue
Erros de ciclo de vida de rascunho
Se kind ou language estiver errado, não tente corrigi-lo.
Estes campos são imutáveis. A recuperação correcta é descartar o rascunho com discard-offering-draft e criar uma nova oferta.
Se uma oferta já tem uma versão publicada actual, descartar o rascunho não remove a versão activa.
Erros de publicação
publish-offering pode falhar se o rascunho estiver incompleto ou inválido.
Recuperação:
- chame
check-offering-publish-readiness - corrija os erros retornados
- tente publicar apenas depois de a prontidão ser confirmada
Falhas de pedido ao servidor
Uma ferramenta pode retornar uma falha de pedido quando o pedido ao servidor falha antes de ser retornada uma resposta válida.
Recuperação:
- repita a mesma operação só de leitura se adequado
- evite repetir chamadas de mutação sem antes verificar o estado actual com
get-offering - reporte a mensagem de erro se a falha persistir