#[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
| Macro | Uso |
|---|---|
require! | Condição booleana |
require_eq! / require_ne! | Verificações de igualdade |
require_keys_eq! | Comparações de Pubkey |
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
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| constraint @ Error | Tempo de validação da conta | Regras de negócios do manipulador |
| Erros customizados nativos | Não-Anchor | Clientes com integração IDL |
FAQs
Formato de erro do Anchor 0.32.1?
Códigos customizados 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 feature.
Como os clientes obtêm os códigos de erro?
Do IDL via Anchor ou geração de código Codama.
Eventos aparecem no IDL?
Sim, tipos #[event] são listados.
Constraints podem retornar erros customizados?
Sim, com @ MyError::Variant.
O que usa CU em logs?
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 erros.
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.