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
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| Eventos para contexto de falha | Detalhes ricos | Mensagens simples para o usuário |
| Metadados de erro off-chain | Tabelas de localização | Códigos canônicos on-chain |
FAQs
Formato de erro do Anchor 0.32.1?
Códigos personalizados no IDL mais strings #[msg].
emit! vs emit_cpi!?
emit_cpi! custa mais CU, mas melhora a confiabilidade da captura.
Devo usar msg! na mainnet?
Evite, exceto atrás de flags de funcionalidade.
Como os clientes obtêm os códigos de erro?
Do IDL via Anchor ou codegen Codama.
Eventos aparecem no IDL?
Sim, tipos #[event] são listados.
Constraints podem retornar erros personalizados?
Sim, com @ MyError::Variant.
O que usa CU em logging?
Cada linha de log e string formatada.
Como testar erros?
anchor test esperando códigos de erro.
Logs são dados de consenso?
Sim, mas não um contrato de API; use eventos.
Próxima leitura?
Veja Relacionados para mensagens de erro.
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.