> 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/api-reference/pt-br/guides/errors.md). # Erros Os códigos de status que o contrato declara, os cabeçalhos de limite de requisições e por que um 401 não diz nada. Cada página de endpoint gerada lista os status que aquela operação declara. Esta página explica o que cada código significa em toda a API, e os dois lugares em que o contrato diz pouco de propósito. ## Modelo de erros | Status | Significado | Observações | | ------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `200` | Sucesso | 123 operações | | `201` | Criado | 5 operações. `POST /orders` e `POST /orders/batch` com seus gêmeos `/api/v1`, e `POST /api/v1/bridge/withdrawals`. | | `101` | Troca de protocolos | Os dois caminhos de upgrade para WebSocket | | `400` | Erro de validação | 50 operações. O corpo carrega um `code` legível por máquina onde o contrato define um, por exemplo `invalid_window`, `bad_wallet`, `bad_agent`, `expiry_out_of_range`, `invalid_json`. As rejeições de ordem cobrem margem insuficiente, tick size inválido, ordens que não podem ser editadas e violação de margem. | | `401` | Falha de autenticação | 89 operações. **Todas as respostas 401 retornam o mesmo corpo opaco, `{"code":"unauthorized"}`, de propósito, para evitar vazamento de informação.** Um 401 não diz *por quê*. Uma chave inválida, uma assinatura inválida, um timestamp velho e uma sessão expirada parecem iguais. Verifique primeiro o desvio de relógio. | | `403` | Proibido | 25 operações. Recusas por controle de jurisdição em escritas de ordem, adição de fundos, alavancagem, margem e saque pela ponte, que são permanentes para a origem de quem chama, então não tente de novo. Os endpoints de administração (exigem o segredo de admin). `POST /account/credit` quando um operador congelou os créditos (`credits_frozen`). `EARLY_ACCESS_REQUIRED` em `GET /account/deposit-target`. Saques recusados em `POST /withdrawals`. `TRANSFER_ACCOUNT_INELIGIBLE` ou `TRANSFER_OUTFLOW_BLOCKED` nas operações `/transfers`. | | `404` | Não encontrado, ou não pertence a você | 26 operações. Falhas de propriedade retornam 404, não 403, então você não consegue sondar os recursos de outras contas. | | `409` | Conflito | 7 operações. `duplicate_agent` no registro de agente. Um `client_id` já reivindicado por uma ordem que não está mais em repouso no livro, no envio de ordens. O controle de admissão do ciclo de vida do mercado em uma edição. Uma `Idempotency-Key` reutilizada com um valor diferente em `POST /api/v1/bridge/withdrawals`. `TRANSFER_ID_CONFLICT` em `POST /transfers`. | | `422` | Não processável | 1 operação. `POST /account/margin-mode` com dados semanticamente inválidos, campos desconhecidos ou um `margin_mode` diferente de `cross` ou `isolated`. JSON malformado é um `400`. | | `426` | Upgrade necessário | 1 operação. `POST /account/deposit` quando uma chave de serviço verificada envia a conta creditada no cabeçalho `X-Account-Id`. Envie `account_id` no corpo assinado. | | `429` | Limite de requisições excedido | 74 operações. Veja abaixo. | | `500` | Erro interno | 3 operações. `INTERNAL_ERROR` em `POST /auth/login` quando a escrita no armazenamento de sessões falha, e um erro interno inesperado em `GET` e `POST /account/margin-mode`. | | `502` | Upstream indisponível | 14 operações. Em `/account/summary` e `/account/state` e seus gêmeos `/api/v1`, `authoritative_margin_unavailable`: a visão de margem que tem o motor como autoridade está temporariamente indisponível. Os endpoints que derivam saldos dela **falham de forma fechada** e retornam o erro em vez de um valor estimado localmente e potencialmente inseguro. É transitório, então tente de novo após um breve intervalo. Os demais são `BAD_GATEWAY` nas leituras de indicações, `FUNDING_SOURCE_*` no snapshot de financiamento, uma etapa downstream com falha em `POST /api/v1/bridge/withdrawals` e resultados `TRANSFER_*` nas operações `/transfers`. | | `503` | Serviço indisponível | 11 operações. `DEPOSIT_TARGET_MISCONFIGURED` em `GET /account/deposit-target`, `REFERRAL_STORE_NOT_CONFIGURED` nas leituras de indicações, `TRANSFERS_UNAVAILABLE` nas operações `/transfers`, saques indisponíveis em `POST /api/v1/bridge/withdrawals` e um ajuste de margem que não pôde ser registrado de forma durável em `POST /account/margin`. | Uma operação é um caminho e método em `openapi.json`, com cada gêmeo `/api/v1` contado separadamente. Uma contagem é o número de operações que declaram aquele status. Para recalculá-las, rode isto a partir da raiz do repositório: ```bash python3 -c 'import json, collections; d = json.load(open("eng/apps/exchange/api/openapi.json")); print(sorted(collections.Counter(code for item in d["paths"].values() for method, op in item.items() if method in ("get", "put", "post", "delete", "patch") for code in op.get("responses", {})).items()))' ``` ### 429 e os cabeçalhos de limite de requisições Um corpo `429` tem a forma `{"code":"RateLimitExceeded","tier":"Pro"}` e a resposta carrega: | Cabeçalho | Significado | | ----------------------- | --------------------------------------------------- | | `X-RateLimit-Limit` | Requisições por segundo permitidas para o seu nível | | `X-RateLimit-Remaining` | Requisições restantes na janela atual | | `X-RateLimit-Reset` | Timestamp Unix em que o limite é reiniciado | | `Retry-After` | Segundos a esperar antes de tentar de novo | Controle o ritmo pelos cabeçalhos `X-RateLimit-*` em vez de tentar de novo às cegas. Dois endpoints reutilizam o `429` com um significado que não é limite de requisições: `POST /account/credit` (franquia diária de crédito esgotada, reinicia à meia-noite UTC) e `POST /faucet` (período de espera ainda não decorrido, ou teto cumulativo atingido). Para os tetos por nível e os limites de conexão, veja [Limites de requisições e de conexão](https://docs.nexus.xyz/exchange/apis-and-rates/rate-limits). ## Compatibilidade com CCXT ### Suporte a versões da API O identificador de versão é a tag de release publicada da spec deste contrato. O edge publica as versões que aceita em `/metadata`, que o edge serve e que **não** é uma operação deste contrato. Ele retorna `current_api_version` (tag mais recente servida) e `min_api_version` (tag mais antiga ainda aceita), para que clientes e agentes possam ler a janela de suporte de forma programática. Antes da 1.0 (`v0.x.y`), mudanças incompatíveis são frequentes e `min_api_version` pode avançar a cada release incompatível. Uma tag publicada continua com suporte por pelo menos **14 dias** após a release que a substitui, e essa janela se amplia depois da 1.0. Uma requisição cujo `X-Nexus-Api-Version` nomeia uma tag reconhecida mais antiga que `min_api_version` recebe um `426 Upgrade Required` legível por máquina (`api_version_unsupported`) com um link para a spec atual, para que as ferramentas possam detectar a defasagem e atualizar. Como o cabeçalho não é autenticado, essa verificação é uma ajuda de compatibilidade, não um controle de segurança. Falsificar o valor só a relaxa. Veja também [Versionamento da API](https://docs.nexus.xyz/exchange/apis-and-rates/api-versioning). --- # 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/api-reference/pt-br/guides/errors.md?ask=&goal= ``` `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.