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

Preguntas frecuentes

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.