> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/exchange/pt-br/apis-and-rates/apis-and-rates/api-versioning.md).

# Versionamento da API

Como a API é versionada, qual versão um cliente recebe e como uma descontinuação é sinalizada.

A API da Nexus Exchange é versionada com a especificação OpenAPI publicada em [`nexus-xyz/nexus-exchange-api`](https://github.com/nexus-xyz/nexus-exchange-api). Cada versão do SDK é fixada em uma versão específica da especificação, e a API declara uma **versão mínima suportada** que ela aceita. Esta página explica como enviar sua versão, o que acontece quando ela fica abaixo do mínimo e como as descontinuações são sinalizadas.

## Enviando sua versão

Envie a tag da especificação com a qual seu cliente foi construído em um cabeçalho de requisição, além do (não em vez do) seu `User-Agent`:

```
X-Nexus-Api-Version: v0.6.2
```

O valor é a tag publicada da especificação (o `v` inicial é opcional, então `v0.6.2` e `0.6.2` são equivalentes). Os SDKs oficiais são fixados em uma versão da especificação e enviam esse cabeçalho por você por padrão; você só precisa defini-lo manualmente se construir seu próprio cliente.

O cabeçalho é **opcional durante o período de carência atual, anterior à 1.0**, e requisições sem ele são aceitas. Isso ficará mais rígido à medida que a API se aproximar do GA, então envie o cabeçalho desde já para manter sua integração compatível com o futuro.

## Versão mínima suportada

A API aceita requisições apenas na versão mínima publicada ou acima dela. Isso evita deixar integrações presas em mudanças incompatíveis sem carregar uma bagagem permanente de compatibilidade retroativa antes de existir uma grande base de clientes externos.

**Política de suporte anterior à 1.0.** Até a versão 1.0 GA, a versão mínima suportada pode avançar de forma agressiva à medida que mudanças incompatíveis são lançadas. A prática operacional quando o mínimo avança é primeiro mover as versões abaixo dele para uma janela de descontinuação (veja abaixo) antes de retirá-las, para que uma integração ativa receba uma janela sinalizada para atualizar. Trate os cabeçalhos de resposta `Deprecation` / `Sunset` como seu sinal oficial de atualização, em vez de presumir um período de carência fixo.

**Como o número avança, e por que o formato dele não é um sinal de compatibilidade.** O contrato é anterior à 1.0, então leia `0.MAJOR.MINOR`: normalmente uma mudança incompatível avança o segundo componente e zera o terceiro (`0.9.41` → `0.10.0`), e uma mudança compatível avança o terceiro (`0.9.41` → `0.9.42`).

Há uma exceção, e ela é o motivo pelo qual você não deve inferir compatibilidade a partir do formato do incremento. Enquanto o contrato neste repositório já estiver à frente da tag publicada mais recente no segundo componente, uma mudança incompatível avança também o **terceiro** componente. Abrir uma segunda linha `0.MAJOR` não publicada deixaria presa a que já está em andamento. Um incremento no terceiro componente, portanto, significa "este é o próximo contrato", não "é seguro adotar isto sem ler". `0.9.41`, que renomeou seis campos de resposta de `GET /orders/history` e mudou a caixa de `side`, é uma dessas versões.

Leia as notas da própria versão e os cabeçalhos `Deprecation` / `Sunset` para decidir se uma versão é segura para sua integração. O número da versão, sozinho, não consegue dizer isso.

Você sempre pode ler o limite atual de forma programática. Consulte [Descobrindo a versão atual](#discovering-the-current-version).

## Abaixo do mínimo: `426 Upgrade Required`

Uma requisição cuja versão está abaixo do mínimo é rejeitada com **HTTP 426 Upgrade Required** e um corpo JSON legível por máquina:

```json
{
  "code": "api_version_unsupported",
  "message": "Unsupported or missing API version. Fetch the current OpenAPI spec at spec_url, regenerate your client, and retry with the X-Nexus-Api-Version header.",
  "min_version": "0.6.0",
  "current_version": "0.6.2",
  "spec_url": "https://github.com/nexus-xyz/nexus-exchange-api/releases",
  "docs_url": "https://docs.nexus.xyz/exchange/apis-and-rates/api-versioning"
}
```

A resposta também traz um cabeçalho `X-Nexus-Api-Min-Version` com o mesmo piso, para clientes que leem cabeçalhos sem analisar o corpo.

**Autorrecuperação para agentes.** Como o corpo traz `spec_url` e tanto a versão mínima quanto a atual, um cliente automatizado consegue se recuperar de uma divergência de versão sozinho. Ele pode buscar a especificação atual, regenerar seu cliente e tentar novamente sem nenhum humano envolvido. Um erro de divergência de versão é uma condição recuperável, não uma quebra silenciosa.

## Descontinuação e sunset

Uma versão que ainda é aceita, mas está agendada para ser retirada, é atendida normalmente, com cabeçalhos de aviso padrão em toda resposta:

* **`Deprecation`** ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) sinaliza que a versão que você enviou está descontinuada.
* **`Sunset`** ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) informa a data após a qual essa versão será rejeitada com `426`.
* **`Link: <…>; rel="deprecation"`** aponta para esta página.

Trate um cabeçalho `Deprecation` como um aviso para atualizar antes da data de `Sunset`. Nada na requisição falha enquanto ela está na janela de descontinuação; apenas os cabeçalhos de aviso são adicionados.

## Detalhes da análise do cabeçalho

Se você construir seu próprio cliente em vez de usar um SDK oficial, observe estes detalhes:

* **Tags de pré-lançamento são comparadas pela linhagem da versão.** Um pré-lançamento como `0.6.0-rc.1` é tratado como `0.6.0` na verificação do mínimo. Tudo a partir do primeiro `-` ou `+` é removido, então um pré-lançamento satisfaz um piso igual à sua versão de lançamento.
* **Uma versão que não pode ser analisada é tratada como ausente.** Durante o período de carência, um `X-Nexus-Api-Version` malformado é aceito e registrado em log, como um cabeçalho ausente. Quando o cabeçalho se tornar obrigatório, ele será rejeitado da mesma forma. Envie uma tag `major.minor.patch` limpa (com um `v` inicial opcional).
* **Preflight de CORS e handshakes de WebSocket nunca são bloqueados.** O preflight `OPTIONS` e os handshakes de upgrade do WebSocket estão isentos, porque um navegador não consegue anexar o cabeçalho a nenhum dos dois, então a verificação nunca os bloqueia.
* **Rotas de descoberta nunca são bloqueadas.** `/metadata`, `/openapi.json`, `/llms.txt` e os documentos `/.well-known/*` continuam acessíveis em qualquer versão, para que um cliente desatualizado sempre consiga buscar o que precisa para se autorrecuperar.

## Descobrindo a versão atual

As versões mínima e mais recente atuais são publicadas em um endpoint de metadados sem autenticação, para que clientes e agentes possam ler o limite sem extrair dados da documentação:

```
GET /metadata
```

```json
{
  "api_version": {
    "header": "x-nexus-api-version",
    "min_supported": "0.6.0",
    "current": "0.6.2",
    "deprecated_below": null,
    "sunset": null,
    "spec_url": "https://github.com/nexus-xyz/nexus-exchange-api/releases",
    "docs_url": "https://docs.nexus.xyz/exchange/apis-and-rates/api-versioning",
    "policy": "pre-1.0: minimum-supported version may advance until GA; missing version header allowed during grace mode"
  }
}
```

`/metadata` está sempre acessível, independentemente da versão que você envia. Caso contrário, um cliente desatualizado nunca conseguiria descobrir o valor de que precisa para atualizar.

## Padrão de cliente recomendado

1. Fixe seu cliente em uma versão publicada da especificação e envie-a em `X-Nexus-Api-Version`.
2. Ao receber um `426 api_version_unsupported`, leia `spec_url` no corpo (ou em `GET /metadata`), regenere o cliente com uma versão `>= min_supported` e tente novamente.
3. Fique atento aos cabeçalhos de resposta `Deprecation` / `Sunset` e atualize antes da data de sunset.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nexus.xyz/exchange/pt-br/apis-and-rates/apis-and-rates/api-versioning.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.