Mensagens de Erro Personalizadas

Use #[msg("...")] em variantes de enum de erro para mensagens padrão. Clientes mapeiam códigos de erro para cópias localizadas usando o IDL.

Receita

#[error_code]
pub enum SwapError {
    #[msg("Slippage tolerance exceeded")]
    SlippageExceeded,
    #[msg("Pool is disabled")]
    PoolDisabled,
}

Quando usar isso: Você lança dApps voltados para o usuário que exibem falhas de programa.

Exemplo Funcional

#[error_code]
pub enum StakeError {
    #[msg("Stake amount below minimum")]
    BelowMinimum,
    #[msg("Unlock period not elapsed")]
    StillLocked,
}
 
// constraint errors
#[account(constraint = !pool.disabled @ SwapError::PoolDisabled)]
pub pool: Account<'info, Pool>,

O que isso demonstra:

• IDL exporta nomes e códigos de erro
• Mesmo código em todos os clusters
• constraint @ mapeia para a variante
• Clientes não devem analisar logs para erros

Mergulho Profundo

Mapeamento do Cliente

Gere tabelas de lookup de erros a partir do IDL em TypeScript. Mostre error.errorCode + mensagem mapeada na UI.

Estabilidade

Não renumerem variantes de erro levianamente; clientes armazenam mapeamentos em cache.

Armadilhas

• Alterar a ordem das variantes - Códigos mudam, quebrando clientes. Correção: Adicione apenas novas variantes.
• Mensagem genérica para muitos casos - UX ruim. Correção: Divida variantes.
• Embutir dados do usuário na macro msg - Não suportado dinamicamente. Correção: Use eventos para detalhes.
• Apenas inglês nas mensagens on-chain - A localização é do lado do cliente. Correção: Mapeie códigos na UI.
• Confiar em strings de log - Logs mudam. Correção: Decodifique erros estruturados.

Alternativas

FAQs

Relacionados

• #[error_code] & require! - declaração
• Decodificação de Erro do Lado do Cliente - TS
• O IDL do Anchor - seção de erros do IDL

Versões da Stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, e LiteSVM 0.6.x.