Mensajes de error personalizados
Utiliza #[msg("...")] en las variantes de enumeración de errores para mensajes predeterminados. Los clientes mapean los códigos de error a texto localizado utilizando el IDL.
Receta
#[error_code]
pub enum SwapError {
#[msg("La tolerancia al deslizamiento ha excedido")]
SlippageExceeded,
#[msg("El pool está deshabilitado")]
PoolDisabled,
}Cuándo usar esto: Cuando distribuyes dApps dirigidas a usuarios que muestran fallos del programa.
Ejemplo funcional
#[error_code]
pub enum StakeError {
#[msg("La cantidad de stake está por debajo del mínimo")]
BelowMinimum,
#[msg("El período de desbloqueo no ha transcurrido")]
StillLocked,
}
// Errores de restricción
#[account(constraint = !pool.disabled @ SwapError::PoolDisabled)]
pub pool: Account<'info, Pool>,Lo que esto demuestra:
- El IDL exporta nombres y códigos de error
- Mismo código en todos los clústeres
constraint @se mapea a la variante- Los clientes no deben analizar los registros en busca de errores
Análisis detallado
Mapeo del cliente
Genera tablas de búsqueda de errores a partir del IDL en TypeScript. Muestra error.errorCode + mensaje mapeado en la UI.
Estabilidad
No renumere las variantes de error a la ligera; los clientes almacenan en caché los mapeos.
Errores comunes
- Cambiar el orden de las variantes - Los códigos cambian, rompiendo los clientes. Solución: Añade solo nuevas variantes.
- Mensaje genérico para muchos casos - Mala experiencia de usuario. Solución: Divide las variantes.
- Incrustar datos de usuario en la macro
msg- No se admite dinámicamente. Solución: Usa eventos para obtener detalles. - Mensaje en cadena solo en inglés - La localización es del lado del cliente. Solución: Mapea códigos en la UI.
- Confiar en cadenas de registro - Los registros cambian. Solución: Decodifica errores estructurados.
Alternativas
| Alternativa | Usar cuándo | No usar cuándo |
|---|---|---|
| Eventos para contexto de fallo | Detalles enriquecidos | Mensajes de usuario simples |
| Metadatos de error fuera de cadena | Tablas de localización | Códigos canónicos en cadena |
Preguntas frecuentes
¿Formato de error de Anchor 0.32.1?
Códigos personalizados en el IDL más cadenas #[msg].
¿emit! vs emit_cpi!?
emit_cpi! cuesta más CU pero mejora la fiabilidad de la captura.
¿Debo usar msg! en mainnet?
Evitar excepto detrás de indicadores de características.
¿Cómo obtienen los clientes los códigos de error?
Desde el IDL a través de Anchor o la generación de código de Codama.
¿Los eventos aparecen en el IDL?
Sí, los tipos #[event] se enumeran.
¿Pueden las restricciones devolver errores personalizados?
Sí, con @ MyError::Variant.
¿Qué usa CU en el registro?
Cada línea de registro y cadena formateada.
¿Cómo probar los errores?
anchor test esperando códigos de error.
¿Son los registros datos de consenso?
Sí, pero no un contrato de API; usa eventos.
¿Próxima lectura?
Ver Relacionados para mensajes de error.
Relacionados
- #[error_code] y require! - declaración
- Decodificación de errores del lado del cliente - TS
- El IDL de Anchor - sección de errores del IDL
Versiones de la pila: Esta página se escribió 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 y LiteSVM 0.6.x.