> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vertracloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Fazer rollback da aplicação para uma release

> Faz o rollback de uma aplicação para uma release anterior, restaurando o código, removendo os arquivos que ela não tinha e reiniciando-a, com variáveis opcionais.

Faz o rollback da aplicação para o código que ela tinha nesta release, depois a reinicia. O rollback é registrado como uma nova release com `source: "rollback"`, então você pode desfazê-lo do mesmo jeito. Opcionalmente, ele também restaura as variáveis de ambiente salvas com essa release.

Fazer rollback não altera os dados que a aplicação criou enquanto roda, como um arquivo de banco de dados ou uploads. Para trazer os dados de volta, use um [snapshot](https://docs.vertracloud.app/pt-br/api-reference/endpoint/apps/snapshots/restore.md).

**id** `string` *required*

O ID da aplicação. Se a aplicação pertencer a um workspace, informe o ID dele no query parameter `workspace_id`.

**release\_id** `string` *required*

O ID da release para a qual fazer o rollback, como retornado pela [lista de releases](https://docs.vertracloud.app/pt-br/api-reference/endpoint/apps/releases/list.md). Precisa ser uma release cujo código ainda é mantido (`rollback.available` é `true`).

**workspace\_id** `string`

Se a aplicação pertencer a um workspace, o ID do workspace.

**restore\_environment** `boolean` (default: false)

Opcional. `true` também substitui as variáveis de ambiente da aplicação pelas salvas com essa release. O padrão `false` mantém as variáveis que a aplicação tem agora. Confira antes as mudanças com a [pré-visualização do rollback](https://docs.vertracloud.app/pt-br/api-reference/endpoint/apps/releases/rollback-preview.md).

O que o rollback faz:

* **Código:** cada arquivo de código da release é restaurado exatamente como estava. Arquivos de código que a release não tinha são apagados.
* **Dados:** arquivos criados pela aplicação enquanto roda não são alterados nem apagados.
* **Variáveis:** não mudam, a menos que `restore_environment` seja `true`.
* **Restart:** a aplicação reinicia com um build forçado, então o comando de build dela roda de novo, se tiver um.
* **Histórico de releases:** a versão que estava rodando passa para `rolled_back`, e a nova release passa a ser a ativa. O `rollback.from` dela é a release que você restaurou.

Outras regras se aplicam:

* Um rollback não usa os slots de deploy do seu plano, mas dois rollbacks da mesma aplicação precisam de pelo menos 30 segundos entre eles. Rollbacks também têm limite horário próprio por conta, igual ao limite horário de deploy do seu plano. Ao ultrapassá-lo, a resposta é `429 DEPLOY_RATE_LIMITED`, com `details.limit`, `details.window_seconds` e `details.retry_after`, e nenhum slot de deploy é usado.
* Se o código da release não puder ser restaurado, a requisição falha com `INTERNAL_SERVER_ERROR`. Nada muda. Se o código salvo dessa release estiver danificado, falha com `INVALID_ZIP_STRUCTURE` (`400`) antes de qualquer arquivo ser tocado.
* Se o restart falhar depois que os arquivos foram restaurados, a resposta é o erro do restart (por exemplo `BUILD_FAILED`). A aplicação já roda o código restaurado, então corrija a causa e reinicie-a.

Só as releases que o seu plano mantém podem ser restauradas. Veja [Histórico de deploys e limites de rollback](https://docs.vertracloud.app/pt-br/plans-and-limits.md#limites-do-histórico-de-deploys-e-do-rollback).

Exige o escopo `apps:write` quando chamado com uma chave de API. Se `restore_environment` for `true`, a chave também precisa do escopo `apps:envs`; sem ele, a requisição retorna `403 API_KEY_SCOPE_DENIED`. Para um membro do workspace, exige as permissões `apps:files` e `apps:lifecycle`, além de `apps:envs` ao restaurar variáveis.

### Resposta

**response** `object`

A nova release criada pelo rollback.

**Mostrar objeto**

**id** `string`

O ID da nova release.

**source** `string`

Sempre `rollback` nesta resposta.

**status** `string`

`active`, a versão que a aplicação roda agora.

**rollback** `object`

**Mostrar objeto**

**available** `boolean`

`false` para a release ativa.

**from** `string`

O ID da release que foi restaurada.

**message** `string | null`

A mensagem da release. `null` quando nenhuma foi informada.

**files\_changed** `integer`

Número de arquivos alterados pela operação que gerou esta release.

**build\_duration\_ms** `integer | null`

Tempo, em milissegundos, gasto no build e na inicialização da aplicação.

**first\_started\_at** `string | null`

Quando a aplicação iniciou pela primeira vez com o código desta release, ou seja, quando o restart do rollback terminou.

**created\_at** `string`

Timestamp ISO de quando o rollback foi feito.

**author** `string`

O nome do usuário que fez o rollback.

**app\_id** `string`

O ID da aplicação.

**github** `null`

`null`, porque um rollback não é um push do GitHub.

**has\_log** `boolean`

`true` quando um log de crash foi registrado para esta release.

```json Response theme={null}
{
  "response": {
    "id": "5b8e3f10-2c4a-4d9b-a7e1-0f3c6b9d2e54",
    "app_id": "7a52e0d4-19b3-4f8e-b6c2-0d9e4a1f5c73",
    "source": "rollback",
    "status": "active",
    "message": null,
    "author": "octocat",
    "github": null,
    "files_changed": 4,
    "rollback": {
      "available": false,
      "expires_at": null,
      "from": "3f1c2a9e-8b7d-4c21-9e0a-5d6f7a8b9c01"
    },
    "has_log": false,
    "build_duration_ms": 12450,
    "first_started_at": "2026-10-11T15:02:50.000Z",
    "created_at": "2026-10-11T15:02:37.000Z"
  }
}
```

### Respostas de erro

**code** `string`

Códigos de erro possíveis:

* `AUTH_TOKEN_MISSING`, `API_KEY_INVALID`, `SESSION_REVOKED`: o header `Authorization` está ausente, a chave de API é inválida ou a sessão do painel foi revogada (`401`).
* `API_KEY_IP_DENIED`: a chave de API é usada a partir de um IP fora da sua allowlist (`403`).
* `APP_NOT_FOUND`: a aplicação não existe, ou não pertence a esta conta ou workspace (`404`).
* `RELEASE_NOT_FOUND`: a release não existe, ou pertence a outra aplicação (`404`).
* `PLAN_DOES_NOT_SUPPORT_ROLLBACK`: o seu plano não inclui fazer rollback para releases anteriores (`403`). O rollback começa no Pro.
* `API_KEY_SCOPE_DENIED`: a chave de API não tem o escopo `apps:write`, ou não tem `apps:envs` enquanto `restore_environment` é `true` (`403`).
* `RELEASE_ALREADY_ACTIVE`: a release já é a que a aplicação roda, ou tem o mesmo código e `restore_environment` não mudaria nada (`409`).
* `RELEASE_EXPIRED`: o código desta release não é mais mantido, porque expirou ou é mais antigo do que o número de releases que o seu plano mantém (`410`).
* `OPERATION_IN_PROGRESS`: outra operação de ciclo de vida na mesma aplicação já está em execução (`409`). Nada foi alterado; aguarde alguns segundos e tente de novo.
* `RESTORE_COOLDOWN`: o rollback anterior desta aplicação foi há menos de 30 segundos (`429`). Aguarde e tente de novo.
* `DEPLOY_RATE_LIMITED`: o limite horário de rollbacks da conta foi atingido (`429`). `details` traz `limit`, `window_seconds` e `retry_after`. Aguarde e tente de novo.

**message** `string`

Uma mensagem descritiva com detalhes adicionais sobre o erro.

```json Error Response (410) theme={null}
{
  "code": "RELEASE_EXPIRED"
}
```

```json Error Response (429) theme={null}
{
  "code": "RESTORE_COOLDOWN"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.