Fundamentos del manejo de errores

10 ejemplos para empezar con Errores y Registros: 7 básicos y 3 intermedios.

Prerrequisitos

• Los manejadores de instrucciones devuelven ProgramResult de Rust para Solana.

Ejemplos básicos

1. ProgramResult

Las instrucciones devuelven Result<(), ProgramError>.

use solana_program::entrypoint::ProgramResult;
 
pub fn handler() -> ProgramResult { Ok(()) }

• Err falla toda la transacción.
• Ok confirma el estado atómicamente con otras instrucciones.
• Usa ? en ayudantes.

2. Errores integrados

El runtime proporciona códigos de error estándar.

return Err(ProgramError::InvalidArgument);

• Portátil entre programas.
• Expresividad limitada para la experiencia del usuario (UX).
• Bueno para fallos de invariantes internas.

3. Código de error personalizado

Códigos u32 específicos del dominio.

return Err(ProgramError::Custom(6001));

• Los clientes mapean a mensajes.
• Documentar por programa.
• Los offsets de Anchor se auto-generan en el IDL.

4. Mapeo desde enum

Implementación From estilo thiserror.

impl From<MyError> for ProgramError {
  fn from(e: MyError) -> Self { ProgramError::Custom(e as u32) }
}

• Habilita la ergonomía de ?.
• Mantener los códigos estables.
• Exportar el enum para el SDK.

5. Sin panic

Nunca uses unwrap en rutas de entrada del usuario.

// MAL: data[0]; // BIEN: data.get(0).ok_or(...)?

• Panic aborta la instrucción.
• Devuelve errores tipados.
• Usa fuzzing para encontrar panics.

6. Errores de CPI

Propaga los fallos del llamado.

invoke(&ix, accounts)?;

• ? propaga ProgramError.
• Mapea si necesitas un código personalizado.
• Los registros pueden mostrar el programa interno.

7. El cliente ve

Transacción fallida con código en metadatos.

// fuera de cadena: parsear registros + código de error

• La simulación previsualiza los mismos códigos.
• Las billeteras muestran un fallo genérico.
• Tu dApp mapea los códigos personalizados.

Ejemplos intermedios

8. Errores de Anchor

Atributo error_code en 0.32.1.

#[error_code]
pub enum Error { InsufficientFunds }

• Exportación automática de IDL.
• Offset a partir de 6000.
• Compatible con decodificadores de @solana/kit.

Relacionado: Enums de error personalizados

9. Registrar en la ruta de error

Mensaje corto para depuración - ten en cuenta las CU.

solana_program::msg!("reject: insufficient");

• Registros públicos - sin secretos.
• Prefiere errores personalizados para la UX.
• Eliminar en rutas críticas de producción.

Relacionado: Registro con msg!

10. Decodificar fuera de cadena

Emparejar código personalizado con enum.

// TS: parsear error de simulación

• El IDL proporciona el mapeo de nombres.
• El nativo necesita una tabla publicada.
• IDL JSON de Anchor lang 0.32.1.

Relacionado: Decodificación de errores fuera de cadena

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.