# Convenções da API

URL: https://0.0.0.0:3002/docs/api

Endereço, versionamento, formato, erros, paginação, idempotência e limites.

Base URL: `https://api.acquacloud.com.br`. Tudo o que está documentado aqui funciona com um [token de API](/docs/api/autenticacao). A lista completa de rotas está na [referência](/docs/api/referencia).

## Versionamento [#versionamento]

Toda rota começa com a versão: `/v1/...`. Mudanças incompatíveis criam `/v2/...`, e a versão anterior continua disponível até ser descontinuada com aviso prévio. Campos novos em respostas não contam como mudança incompatível: ignore campos desconhecidos.

## Formato [#formato]

* JSON em UTF-8. Corpo de até 100 KB (uploads de .zip e de arquivos têm limites próprios).
* Datas em ISO 8601 com fuso (`2026-10-06T22:00:00.000Z`).
* IDs são UUIDv7.
* Toda resposta traz `X-Request-Id`. Você pode enviar o seu (8 a 64 caracteres `[A-Za-z0-9_-]`) para correlacionar com os seus logs.

## Erros [#erros]

Erros seguem a [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457), com `Content-Type: application/problem+json`:

```json
{
  "title": "Alguns campos estão inválidos.",
  "status": 400,
  "code": "validation_failed",
  "requestId": "0b9f…",
  "errors": [{ "path": "memoryMb", "message": "Mínimo: 100 MB", "code": "custom" }]
}
```

Baseie a lógica no campo **`code`**, que é estável. `title` e `detail` são textos para pessoas e podem mudar. Veja os [códigos de erro](/docs/api/erros).

Um recurso de outro workspace responde **404**, não 403: a API não revela a existência de recursos aos quais você não tem acesso.

## Paginação [#paginação]

Listas grandes usam cursor: `?limit=25&cursor=…`, com a resposta `{ "data": [...], "nextCursor": "…" }`. `limit` vai de 1 a 100 (padrão 25). Quando `nextCursor` vier `null`, não há mais páginas.

## Idempotência [#idempotência]

Requisições `POST` aceitam o header `Idempotency-Key` (8 a 200 caracteres) para retentativas seguras:

| Situação                               | Resposta                                             |
| -------------------------------------- | ---------------------------------------------------- |
| Mesma chave e mesmo corpo              | A resposta original, com `Idempotent-Replayed: true` |
| Mesma chave e corpo diferente          | `422 idempotency_conflict`                           |
| Primeira requisição ainda em andamento | `409 idempotency_in_progress`                        |
| Erro na primeira tentativa             | A chave é liberada para nova tentativa               |

As chaves valem por 24 horas, por token.

## Limites de requisição [#limites-de-requisição]

* 300 requisições por minuto por IP, com os headers `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset`.
* Ao exceder, a API responde `429 rate_limited` com `Retry-After`.