#[error_code] & require!

Enums #[error_code] mapeiam para códigos de erro estáveis no IDL. require! e similares afirmam condições com esses erros.

Receita

#[error_code]
pub enum MyError {
    #[msg("Amount must be positive")]
    InvalidAmount,
}
 
require!(amount > 0, MyError::InvalidAmount);
require_eq!(owner, ctx.accounts.authority.key(), MyError::Unauthorized);

Quando usar isso: Você precisa de falhas tipadas e decodificáveis pelo cliente.

Exemplo Funcional

#[error_code]
pub enum VaultError {
    #[msg("Vault is paused")]
    Paused,
    #[msg("Insufficient balance")]
    InsufficientFunds,
    #[msg("Math overflow")]
    Overflow,
}
 
pub fn withdraw(ctx: Context<Withdraw>, amount: u64) -> Result<()> {
    require!(!ctx.accounts.vault.paused, VaultError::Paused);
    require!(ctx.accounts.vault.balance >= amount, VaultError::InsufficientFunds);
    ctx.accounts.vault.balance = ctx.accounts.vault.balance
        .checked_sub(amount)
        .ok_or(VaultError::Overflow)?;
    Ok(())
}

O que isso demonstra:

• Erros aparecem no IDL para clientes
• #[msg] define o texto legível por humanos
• require_eq! compara valores
• Use Result? para mapeamento de erros de CPI

Mergulho Profundo

Macros

Anchor atribui códigos de erro começando em um offset personalizado; clientes decodificam via IDL.

Armadilhas

• Raw ProgramError::Custom - Clientes perdem o mapeamento do IDL. Correção: Use #[error_code].
• Mensagens de erro duplicadas - Confusão de suporte. Correção: Uma variante por falha distinta.
• require em loops apertados - Custo de CU aumenta. Correção: Valide uma vez antes do loop.
• Vazamento de estado interno em msg - Vazamento de informações de segurança. Correção: Mantenha as mensagens seguras para o usuário.
• Esquecer ? em CPI - Erro engolido. Correção: Propague com ? ou map_err.

Alternativas

FAQs

Relacionados

• Mensagens de Erro Customizadas - mensagens
• Decodificação de Erro no Lado do Cliente - decodificação TS
• Noções Básicas de Erros de Programa - erros nativos

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.