# Idempotente: o que significa, com exemplos simples

> Entenda o que é idempotente com exemplos de matemática, código, HTTP e pipelines de dados, e veja como fazer reexecuções sem duplicatas.

Source: https://www.erathos.com/blog/idempotente-significado
Published: 2026-11-04
Category: Engenharia de Dados

![Idempotente: o que significa, com exemplos simples](https://cms-media.erathos.com/Idempotente.png)

Imagine um job de dados que carrega os pedidos de ontem e falha bem perto do fim. Se o job for idempotente, quando alguém rodar de novo, a tabela de pedidos vai ficar exatamente como se o job tivesse dado certo na primeira vez. Se o job não for idempotente, alguns pedidos vão aparecer duplicados na tabela de pedidos, e o relatório de receita vai sair errado.

A palavra "idempotente" nasceu na matemática, mas hoje é comum em software, onde descreve quais requisições web podem ser repetidas automaticamente pela aplicação com segurança e quais jobs de dados podem ser reexecutados por pessoas com segurança, sem precisar de nenhuma limpeza.

## O que significa idempotente?

Uma operação idempotente tem o mesmo efeito, seja executada uma vez ou várias vezes. Por exemplo, apertar o botão de chamar o elevador cinco vezes tem o mesmo efeito que apertar uma vez: vem um elevador.

Em inglês, a palavra se pronuncia "EYE-dem-POH-tent" (o [Merriam-Webster](https://www.merriam-webster.com/dictionary/idempotent) registra ˈī-dəm-ˌpō-tᵊnt). Ela foi [cunhada em 1870](https://en.wikipedia.org/wiki/Idempotence) pelo matemático americano Benjamin Peirce. Vem da junção de duas palavras latinas, idem (que significa mesmo) e potent (que significa potência), então quer dizer literalmente "a mesma potência". Peirce usou a palavra para descrever quantidades algébricas que não mudavam quando elevadas a alguma potência.

Na matemática, uma função f é idempotente quando aplicá-la duas vezes dá o mesmo resultado que aplicá-la uma vez:

`f(f(x)) = f(x)`

A função valor absoluto:

Agora podemos generalizar esse padrão para software: em vez de uma "função" como entrada, temos uma "função" como ação. Uma requisição web, um job, uma escrita no banco de dados. Na primeira vez que rodamos, algo muda, e as execuções seguintes deixam tudo como está.

## Exemplos de idempotência no dia a dia e na matemática

O teste mais rápido é simples. Faça a ação uma vez e anote o resultado. Depois faça de novo sobre esse resultado e compare:

Ação

Depois de uma vez

Depois de novo

Idempotente?

Valor absoluto de -11

11

11

Sim

Arredondar 4,7 para baixo (floor)

4

4

Sim

Pegar o maior entre x e 5, com x = 2

5

5

Sim

Unir o conjunto {1, 2} com ele mesmo

{1, 2}

{1, 2}

Sim

Elevar 1 ao quadrado

1

1

Sim

Elevar 2 ao quadrado

4

16

Não

Somar 1 a 10

11

12

Não

Apertar o botão de chamar o elevador

Um elevador a caminho

Continua um elevador

Sim

Apertar o botão "abrir porta" do elevador

A porta fica aberta

A porta fica aberta por mais tempo

Não

[Só 0 e 1 são números inteiros idempotentes](https://en.wikipedia.org/wiki/Idempotence) na multiplicação: 0 × 0 = 0 e 1 × 1 = 1. Floor, ceiling e valor absoluto são algumas funções idempotentes. O botão "abrir porta" não é idempotente porque apertá-lo uma vez gera mais espera do que não apertar, e apertar duas vezes gera ainda mais espera.

Mas espera aí. E se encadearmos duas operações idempotentes? A combinação também é idempotente? Vamos testar: "o maior entre x e 5" e "o resto da divisão por 3". As duas são idempotentes isoladamente. Agora vamos encadeá-las começando com 7. O maior entre 7 e 5 é 7. 7 dividido por 3 deixa resto 1. Vamos repetir a cadeia com 1. O maior entre 1 e 5 é 5. 5 dividido por 3 deixa resto 2. Opa! A segunda execução mudou o resultado. [As operações encadeadas não são idempotentes](https://en.wikipedia.org/wiki/Idempotence). Isso significa que ainda precisamos testar a reexecução do job de dados inteiro, mesmo sabendo que cada etapa isolada é idempotente.

## Código idempotente: definir um valor vs somar a ele

O código segue a mesma regra. Definir um valor é idempotente, e somar a um valor não é. Este pequeno script em Python chama cada tipo de função três vezes, como um retry faria:

`def add_one(value):`
`    return value + 1`


`def set_balance(account, amount):`
`    account["balance"] = amount`


`def deposit(account, amount):`
`    account["balance"] += amount`


`print("add_one(10): once =", add_one(10), "; twice =", add_one(add_one(10)))`
`print("abs(-11): once =", abs(-11), "; twice =", abs(abs(-11)))`

`account = {"balance": 0}`
`for _ in range(3):`
`    set_balance(account, 100)`
`print("set_balance(100) called 3 times: balance =", account["balance"])`

`account = {"balance": 0}`
`for _ in range(3):`
`    deposit(account, 100)`
`print("deposit(100) called 3 times: balance =", account["balance"])`

Saída:

`add_one(10): once = 11 ; twice = 12`
`abs(-11): once = 11 ; twice = 11`
`set_balance(100) called 3 times: balance = 100`
`deposit(100) called 3 times: balance = 300`

`set_balance` pode ser executada uma ou cem vezes, e o saldo continua 100. `deposit` soma 100 a cada execução, ou seja, dois retries resultariam em três depósitos. Isso importa em casos como timeouts de chamadas de rede, em que quem fez a chamada não tem certeza se a primeira tentativa deu certo ou não. Com uma ação de "definir", basta tentar de novo, mas com uma ação de "somar", um retry pode significar pagar o cliente em dobro.

## Quais métodos HTTP são idempotentes?

Os métodos GET, HEAD, OPTIONS, TRACE, PUT e DELETE são idempotentes. POST não é. PATCH não tem garantia de ser. Um método é considerado idempotente se [várias requisições idênticas têm o mesmo efeito pretendido no servidor que uma única requisição](https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods).

Esta é a lista completa do padrão HTTP, mais o PATCH:

Método

Seguro (somente leitura)

Idempotente

GET

Sim

Sim

HEAD

Sim

Sim

OPTIONS

Sim

Sim

TRACE

Sim

Sim

PUT

Não

Sim

DELETE

Não

Sim

POST

Não

Não

PATCH

Não

[Sem garantia](https://developer.mozilla.org/en-US/docs/Glossary/Idempotent)

CONNECT

Não

Não

Já o PUT é idempotente porque a finalidade dele é "guardar exatamente isto aqui". Então, se você enviar a requisição duas vezes, a mesma coisa vai ficar guardada no mesmo lugar. POST costuma significar "adicionar um novo", então se você enviar `POST /add_row` 3 vezes, [vão ser adicionadas 3 linhas](https://developer.mozilla.org/en-US/docs/Glossary/Idempotent).

O conceito de idempotência é definido no nível dos efeitos sobre os dados do servidor. Ele não determina qual deve ser a resposta do servidor ao cliente. Assim, o primeiro DELETE de um registro pode retornar 200, enquanto os seguintes retornam 404, mas em todos os casos o resultado é o mesmo: o registro deixou de existir. Isso também não impede o servidor de registrar cada requisição em uma linha separada nos logs.

A importância das operações idempotentes é que o software pode reenviá-las sem perguntar antes ao usuário. Um cliente [não deve repetir automaticamente requisições não idempotentes](https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods), a menos que tenha como saber que é seguro repetir aquela requisição. Um proxy não pode repeti-las. Por exemplo, uma requisição POST pode criar um pedido, e um retry às cegas dessa requisição pode criar um segundo pedido.

Para permitir que os clientes usem idempotência em APIs que cobram cartões ou criam recursos, muitas APIs usam o conceito de chave de idempotência (idempotency key). O cliente pode criar um ID único para a ação que está executando e enviá-lo junto com a requisição. As requisições seguintes com o mesmo ID podem ser respondidas com o resultado da primeira, evitando executar a mesma operação duas vezes. Por exemplo, a [API da Stripe](https://docs.stripe.com/api/idempotent_requests) para pagamentos com cartão funciona assim:

- O cliente gera a chave. A Stripe recomenda usar UUIDs V4 aleatórios. Uma chave pode ter até 255 caracteres.
- A Stripe salva o código de status e o corpo da primeira requisição feita com a chave de idempotência. Um retry da requisição faz a resposta salva ser retornada. Isso vale mesmo se a primeira requisição tiver retornado um erro.
- A Stripe pode remover chaves com pelo menos 24 horas de existência.
- Se a mesma chave for reutilizada com parâmetros diferentes, a Stripe retorna um erro.

A API da AWS também pode usar um ID fornecido por quem faz a chamada. Sem o ID, [uma requisição com falha para criar um volume de armazenamento EBS pode resultar na criação de dois volumes](https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/) em vez do único que se queria.

Com a chave de idempotência, o fluxo completo de retry fica assim:

## Por que a idempotência importa em pipelines de dados

Muitos schedulers (como o Airflow) têm alguma forma de [retry em caso de falha da task](https://airflow.apache.org/docs/apache-airflow/stable/best-practices.html). Isso significa que qualquer task de um pipeline pode ser executada várias vezes sobre um mesmo conjunto de dados, por causa de algum problema temporário (uma API de origem dá timeout, a conexão com o warehouse cai etc.).

Um padrão clássico de falha é rodar um sync, inserir um lote de linhas e falhar antes de salvar a posição (por exemplo, o último ID ou timestamp lido, ou seja, o cursor). Na reexecução seguinte, começamos da última posição conhecida e, com isso, processamos algumas linhas pela segunda vez.

Agora vamos ver como isso fica em cada abordagem de escrita de dados:

Se isso gera duplicatas ou não depende de como o job escreve. Este script carrega os mesmos três pedidos três vezes em duas tabelas. Uma tabela recebe um INSERT simples. A outra recebe um upsert, que insere uma linha ou a atualiza se já existir uma linha com aquele ID:

`import sqlite3`

`INSERT_SQL = "INSERT INTO orders_insert (id, amount) VALUES (?, ?)"`
`UPSERT_SQL = """\`
`INSERT INTO orders_upsert (id, amount) VALUES (?, ?)`
`ON CONFLICT(id) DO UPDATE SET amount = excluded.amount`
`"""`

`batch = [(1, 50.0), (2, 20.0), (3, 75.0)]`
`connection = sqlite3.connect(":memory:")`
`with connection:`
`    connection.execute("CREATE TABLE orders_insert (id, amount)")`
`    connection.execute("CREATE TABLE orders_upsert (id INTEGER PRIMARY KEY, amount)")`
`    for _ in range(3):`
`        connection.executemany(INSERT_SQL, batch)`
`        connection.executemany(UPSERT_SQL, batch)`

`insert_count = connection.execute("SELECT COUNT(*) FROM orders_insert").fetchone()[0]`
`upsert_count = connection.execute("SELECT COUNT(*) FROM orders_upsert").fetchone()[0]`
`print("Plain INSERT after 3 batch loads: row count =", insert_count)`
`print("UPSERT after 3 batch loads: row count =", upsert_count)`
`connection.close()`

Saída:

`Plain INSERT after 3 batch loads: row count = 9`
`UPSERT after 3 batch loads: row count = 3`

A tabela com INSERT tem 9 linhas para 3 pedidos, então a receita total fica três vezes maior do que deveria. A tabela com upsert tem 3 linhas, não importa quantas vezes o lote rode, por causa da primary key, que identifica cada pedido de forma única.

Existem três formas típicas de garantir idempotência ao carregar dados:

1. Upsert ou merge por uma chave única. Essa abordagem é recomendada pelo guia do Airflow, que orienta a [substituir INSERT por UPSERT](https://airflow.apache.org/docs/apache-airflow/stable/best-practices.html) quando as tasks são reexecutadas. O dbt também usa essa abordagem nos incremental models quando informamos uma `unique_key`. [Em vez de apenas adicionar novas linhas](https://docs.getdbt.com/docs/build/incremental-models), a chave única é usada para atualizar as linhas existentes. Sem uma chave única, a maioria dos data warehouses apenas adicionaria novas linhas às tabelas existentes.
2. Sobrescrever uma fatia fixa dos dados. Um job que reconstrói um dia de dados (uma partição) ou até a tabela inteira sempre vai resultar nos mesmos dados depois de rodar.
3. Fixar a janela de tempo de um job. Um job que usa a data agendada em vez da hora atual do sistema vai processar os dados do mesmo dia mesmo se for reexecutado na semana seguinte.

## Idempotente vs seguro, puro, determinístico e nulipotente

Várias palavras soam parecidas com idempotente e acabam sendo confundidas com ela. Veja como elas se diferenciam:

Termo

O que significa

Exemplo

Idempotente

Fazer de novo não muda nada depois da primeira vez

PUT, DELETE, valor absoluto

Seguro (HTTP)

A requisição só lê e não muda nada no servidor

GET, HEAD

Nulipotente

Não tem efeito nenhum, nem na primeira vez

Ler uma linha de uma tabela

Função pura

Sem efeitos colaterais, e a mesma entrada sempre gera a mesma saída

x + 1

Determinístico

A mesma entrada sempre gera a mesma saída

x + 1

Todo método seguro é idempotente, mas [PUT e DELETE são idempotentes sem serem seguros](https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods). Operações [nulipotentes](https://en.wikipedia.org/wiki/Idempotence) (como a leitura) são os casos mais fortes, em que nem a primeira operação altera o estado.

x + 1 é pura e determinística, mas ainda assim não é idempotente, porque aplicar a função de novo sobre o resultado gera um resultado diferente.

## Como a Erathos lida com reexecuções

A Erathos move dados de bancos de dados, aplicações SaaS e APIs para o seu data warehouse. O que uma reexecução faz em cada tabela de destino depende do [tipo de sync](https://docs.erathos.com/platform/connections/sync-types) que você escolhe para ela:

Tipo de sync

O que faz

Duplicatas após reexecução?

Full Refresh

Lê a tabela de origem inteira e sobrescreve todos os valores no destino

Não

Partial Overwrite

Insere registros novos, e registros atualizados sobrescrevem os desatualizados

Não

Partial Append

Insere todos os registros, então um registro atualizado existe tanto na versão antiga quanto na nova

Sim, de propósito

Partial Versioned

Insere todos os registros e sinaliza qual é a versão mais recente

Versões antigas ficam, sinalizadas

Já os syncs parciais buscam apenas registros posteriores a um cursor. Normalmente ele é a data de criação, a data de atualização ou um ID. Para rodar um sync parcial, você precisa informar uma primary key e uma coluna de data/datetime para o cursor. A Erathos sugere o Partial Overwrite como tipo de sync padrão na plataforma. Existem três tipos de sync parcial, conforme explicado na documentação:

Com Partial Append e Partial Versioned, todas as versões são mantidas de propósito. Esses tipos servem para casos de uso em que você precisa de um histórico de alterações. Depois, você usa queries para pegar a linha mais recente.

Também existem algumas configurações adicionais na Erathos que ajudam a lidar com erros ou inconsistências que possam acontecer:

- Enable Full On: agenda syncs completos regulares para corrigir inconsistências entre a origem e o destino
- [Custom retry strategy](https://docs.erathos.com/platform/connections/custom-retry-strategy): essa configuração (disponível nos planos PRO e Enterprise) define quantas vezes a Erathos deve tentar buscar os dados antes de gerar um erro e enviar um alerta, com pausas configuráveis entre as tentativas

Vale lembrar que, ao rodar um sync com cursor, linhas apagadas na origem não são apagadas no destino, porque o sync não tem como saber dessas linhas apagadas (elas não vão aparecer na busca de registros posteriores ao cursor). Leia [este artigo](https://www.erathos.com/blog/cursor-based-sync-vs-change-data-capture) para entender como ler o log de alterações do banco de dados, que é uma solução para detectar linhas apagadas.

## FAQ

**Qual é a forma mais simples de definir idempotente?** Uma ação é idempotente se, ao fazê-la de novo, o estado final for o mesmo de quando ela foi feita uma vez. Na matemática, isso pode ser expresso como f(f(x)) = f(x).

**GET é idempotente?** Sim, no padrão HTTP o GET é seguro e idempotente. Isso porque o GET apenas recupera dados.

**POST é idempotente?** Não, requisições POST geralmente criam recursos. Fazer três POSTs pode criar três registros. Porém, algumas APIs (como a da Stripe) permitem que o cliente informe uma chave de idempotência, o que torna seguro repetir POSTs.

**PUT é idempotente?** Sim, o PUT substitui o recurso pelos dados exatos que você envia. Enviar os mesmos dados de novo resulta no mesmo estado.

**Qual é a diferença entre seguro e idempotente?** Seguro significa que a requisição não muda nada. Idempotente significa que repeti-la não muda nada além do que a primeira vez já mudou. Métodos seguros são idempotentes, e o DELETE é idempotente, mas não é seguro.

**Idempotente significa que a resposta é sempre a mesma?** Não, por exemplo, um segundo DELETE pode retornar 404 em vez de 200. A idempotência se refere apenas ao estado final dos dados. E o servidor ainda pode registrar cada requisição no log.

**Como deixo um pipeline de dados idempotente?** Escreva com upsert ou merge por uma primary key, ou sobrescreva uma fatia fixa dos dados (por exemplo, um dia). Use a data agendada da execução como janela de tempo. Depois, reexecute o job inteiro sobre os mesmos dados e confira se a contagem de linhas não muda.

## Teste a Erathos grátis por 14 dias

Escolha um tipo de sync para cada tabela e veja o que uma reexecução faz no seu warehouse. [Teste a Erathos grátis por 14 dias](https://app.erathos.com/signup).
