Enums de Errores Personalizados

Los enums de errores personalizados traducen fallos de negocio a códigos estables u32. Anchor los publica en el IDL; los programas nativos deberían distribuir JSON equivalente para los clientes de @solana/kit 7.0.0.

Receta

#[repr(u32)]
pub enum VaultError {
    InsufficientFunds = 6000,
    SlippageExceeded = 6001,
}

Cuándo usar esto:

• Al construir dApps orientadas al usuario que muestran errores específicos.
• Para soportar mensajes de error i18n fuera de la cadena.
• Al auditar modos de fallo.

Ejemplo Funcional

#[error_code]
pub enum Error {
    #[msg("Fondos insuficientes")]
    InsufficientFunds,
    #[msg("Deslizamiento excedido")]
    SlippageExceeded,
}

Lo que esto demuestra:

• El atributo de Anchor genera códigos + IDL.
• Las cadenas Msg son pistas fuera de la cadena.
• El ordenamiento estable es importante.

Análisis Profundo

Rangos de Códigos

• Anchor: 6000+
• Nativo: elegir un rango no utilizado por programa

Exportación IDL

Los clientes decodifican el nombre + código.

Notas de Rust

return Err(Error::InsufficientFunds.into());

Trampas

• Reordenar enum - Cambia los códigos - rompe el cliente. Solución: Añadir solo al final.
• Códigos duplicados entre programas - Confusión en logs en transacciones multi-CPI. Solución: Nombrar en la UI por ID de programa.
• Filtrar pistas de explotación en msg - Las cadenas msg detalladas son públicas. Solución: Texto genérico para el usuario fuera de la cadena.
• Demasiado granular - Cientos de códigos difíciles de mantener. Solución: Agrupar lógicamente.
• No publicar IDL - Los clientes muestran error desconocido. Solución: Publicar artefacto IDL en CI.

Alternativas

Preguntas Frecuentes

Relacionado

• Manejo de Errores en Cadena - Patrones
• Decodificación de Errores Fuera de Cadena - Clientes
• Código de Error y require! - Errores de Anchor

Versiones de Stack: Esta página fue 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, y LiteSVM 0.6.x.