---
title: "Error Set em Zig — O que é e Como Usar"
url: "https://ziglang.com.br/glossario/error-set-em-zig-o-que-%C3%A9-e-como-usar/"
markdown_url: "https://ziglang.com.br/glossario/error-set-em-zig-o-que-%C3%A9-e-como-usar.MD"
description: "Entenda Error Sets em Zig: conjuntos tipados de erros que definem quais falhas uma função pode produzir. Guia completo com exemplos em pt-BR."
date: "2026-02-21"
author: "Zig Brasil"
---

# Error Set em Zig — O que é e Como Usar

Entenda Error Sets em Zig: conjuntos tipados de erros que definem quais falhas uma função pode produzir. Guia completo com exemplos em pt-BR.


# Error Set em Zig — O que é e Como Usar

## Definição

Um **Error Set** em Zig é um tipo que define um **conjunto finito de erros nomeados** que uma função pode retornar. É a parte "erro" de um [Error Union](/glossario/error-union/). Error sets permitem que o sistema de tipos rastreie exatamente quais erros podem ocorrer em cada ponto do programa.

Error sets são representados internamente como inteiros, tornando-os extremamente eficientes — comparáveis a enums em termos de performance.

## Por que Error Sets Importam

1. **Documentação no tipo**: A assinatura da função declara exatamente quais erros pode produzir.
2. **Exaustividade**: O compilador pode verificar se todos os casos de erro foram tratados em um `switch`.
3. **Composição**: Error sets podem ser unidos com o operador `||`, combinando erros de diferentes fontes.
4. **Eficiência**: Representados como inteiros compactos, sem alocação.

## Exemplo Prático

### Declarando um Error Set

```zig
const ArquivoError = error{
    ArquivoNaoEncontrado,
    PermissaoNegada,
    DiskCheio,
};

fn abrirConfiguracao() ArquivoError![]const u8 {
    // Pode retornar qualquer erro do ArquivoError
    return ArquivoError.ArquivoNaoEncontrado;
}
```

### Combinando Error Sets

```zig
const IoError = error{
    Timeout,
    ConexaoRecusada,
};

const AppError = error{
    ConfigInvalida,
    VersaoIncompativel,
};

// União de error sets
const TodosOsErros = IoError || AppError;

fn inicializar() TodosOsErros!void {
    // Pode retornar erros de ambos os conjuntos
}
```

### Switch Exaustivo em Erros

```zig
const std = @import("std");

const ParseError = error{
    CaractereInvalido,
    FormatoIncorreto,
    NumeroGrande,
};

fn parsear(input: []const u8) ParseError!u32 {
    _ = input;
    return ParseError.FormatoIncorreto;
}

pub fn main() void {
    const resultado = parsear("abc");
    if (resultado) |valor| {
        std.debug.print("Valor: {}\n", .{valor});
    } else |err| switch (err) {
        ParseError.CaractereInvalido => std.debug.print("Caractere inválido\n", .{}),
        ParseError.FormatoIncorreto => std.debug.print("Formato incorreto\n", .{}),
        ParseError.NumeroGrande => std.debug.print("Número grande demais\n", .{}),
    }
}
```

### Error Set Inferido

Quando você omite o error set, o compilador o infere automaticamente:

```zig
// O compilador calcula todos os erros possíveis
fn processar() !void {
    try etapa1();  // Erros de etapa1
    try etapa2();  // + Erros de etapa2
    try etapa3();  // + Erros de etapa3
    // Error set final = união de todos
}
```

### anyerror

O tipo `anyerror` é o superconjunto de todos os error sets. Qualquer erro pode ser convertido para `anyerror`:

```zig
fn logErro(err: anyerror) void {
    std.debug.print("Erro: {s}\n", .{@errorName(err)});
}
```

## Armadilhas Comuns

- **Usar `anyerror` em APIs públicas**: Perde-se a documentação de quais erros são possíveis. Prefira error sets explícitos.
- **Error sets muito grandes**: Se sua função pode retornar dezenas de erros diferentes, talvez seja hora de refatorar.
- **Esquecer que error sets são tipos**: Você pode usar `@TypeOf`, `@errorName` e outras built-ins para introspecção.
- **Confundir com enums**: Error sets parecem enums, mas são um sistema à parte com semântica específica.

## Termos Relacionados

- [Error Union](/glossario/error-union/) — Tipo que combina error set com payload
- [Try](/glossario/try/) — Propagação automática de erros
- [Catch](/glossario/catch/) — Captura e tratamento de erros
- [Errdefer](/glossario/errdefer/) — Limpeza condicional em caso de erro

## Error Sets em APIs Públicas

Ao projetar uma biblioteca, usar error sets explícitos em vez de `anyerror` é uma das formas mais eficazes de documentar o comportamento esperado. O tipo de retorno torna-se parte da interface da API:

```zig
/// Erros que podem ocorrer ao conectar ao banco de dados
pub const ConexaoError = error{
    HostNaoEncontrado,
    TimeoutDeConexao,
    AutenticacaoFalhou,
    VersaoIncompativel,
};

/// Erros que podem ocorrer em queries
pub const QueryError = error{
    SyntaxeInvalida,
    TabelaNaoExiste,
    PermissaoNegada,
    ResultadoVazio,
};

/// Todos os erros do módulo de banco
pub const DatabaseError = ConexaoError || QueryError;

pub fn conectar(host: []const u8) ConexaoError!Conexao {
    _ = host;
    return error.HostNaoEncontrado;
}

pub fn query(conn: Conexao, sql: []const u8) QueryError!Resultado {
    _ = conn;
    _ = sql;
    return error.SyntaxeInvalida;
}
```

## Introspecção de Error Sets

O Zig oferece built-ins para trabalhar com error sets em comptime:

```zig
const std = @import("std");

const MeuError = error{
    Overflow,
    DivisaoPorZero,
    ValorInvalido,
};

// Obter o nome de um erro como string
pub fn nomeDoErro(err: MeuError) []const u8 {
    return @errorName(err);
}

// Obter o valor inteiro de um erro
pub fn idDoErro(err: MeuError) u16 {
    return @intFromError(err);
}

test "introspecção de erros" {
    const err = MeuError.Overflow;
    try std.testing.expectEqualStrings("Overflow", @errorName(err));
}
```

## Comparação com Outras Linguagens

Em Rust, erros são tipos que implementam a trait `Error`, geralmente definidos como enums. Em Go, erros são valores da interface `error`. Em C++, exceções são objetos de qualquer tipo derivado de `std::exception`. A abordagem do Zig com error sets é mais próxima de Rust (enums de erros tipados), mas com a vantagem de que a união de error sets e a inferência automática reduzem a quantidade de código boilerplate necessário.

A principal diferença em relação a exceções (Java, C++, Python) é que em Zig os erros são valores — eles não têm custo em tempo de execução quando não ocorrem e não têm stack unwinding automático.

## Tutoriais Relacionados

- [Tratamento de Erros em Zig](/tutoriais/tratamento-de-erros-em-zig/)
- [Introdução ao Zig](/tutoriais/introducao-ao-zig/)