# Regras da API

As regras que valem em todas as operações: erros, limites, paginação, repetições e os modos Sandbox e Produção.

Actualizado em 05/11/2026

Estas regras valem em todas as operações da API. Nesta página:

- [Erros](https://docs.interweb.ao/pt/api-rules.md): O formato dos erros, a lista de códigos e o que fazer em cada caso.
- [Limites](https://docs.interweb.ao/pt/api-rules.md): Quantos pedidos pode fazer, como saber quantos restam e o que fazer quando passa o limite.
- [Paginação](https://docs.interweb.ao/pt/api-rules.md): Como as operações de lista dividem os resultados em páginas.
- [Repetições (Idempotency-Key)](https://docs.interweb.ao/pt/api-rules.md): Como repetir um pedido com segurança, sem fazer a mesma coisa duas vezes.
- [Sandbox e Produção](https://docs.interweb.ao/pt/api-rules.md): Os dois modos da API: o que as chaves sandbox_ e prod_ fazem, e como confirmar o modo em cada pedido.

## Erros

### Formato

Todos os erros têm a mesma forma:

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Demasiados pedidos. Tente de novo daqui a pouco.",
    "correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "details": {
      "retry_after": 42
    }
  }
}
```

| Campo | O que é |
|---|---|
| `code` | Código estável, em inglês. Use este campo nos seus programas. |
| `message` | Texto para pessoas, na língua de `Accept-Language`. Pode mudar: não o use em comparações. |
| `correlation_id` | Identificador do pedido. É o mesmo do cabeçalho `X-Correlation-ID`. |
| `details` | Dados extra sobre o erro. Pode vir vazio. |

### Códigos

| Estado | Código | O que quer dizer | O que fazer |
|---|---|---|---|
| 400 | `invalid_request` | O pedido não é válido, por exemplo o corpo não é JSON ou a ligação não é HTTPS. | Corrija o pedido. |
| 401 | `unauthorized` | A chave está em falta, não é válida, foi revogada ou passou da validade, ou quem a criou já não tem acesso à conta. | Confirme a chave ou crie outra. |
| 402 | `insufficient_credit` | A conta não tem saldo suficiente. Nada foi cobrado. | Carregue o saldo e repita. |
| 403 | `forbidden` | A conta não pode usar a API neste momento. | Contacte o suporte. |
| 403 | `insufficient_scope` | A chave não tem a permissão necessária. | Crie uma chave com essa permissão. |
| 403 | `ip_not_allowed` | O IP de origem não está na lista da chave. | Use um IP da lista ou crie outra chave. |
| 403 | `spending_limit_exceeded` | A operação passa o limite de gastos da chave. Nada foi cobrado. | Crie uma chave com um limite maior. |
| 403 | `sms_reseller_required` | Esta conta não tem revenda de SMS activa. | Active a revenda de SMS no portal da conta. |
| 404 | `not_found` | O recurso não existe ou não é da sua conta. | Confirme o endereço e o identificador. |
| 405 | `method_not_allowed` | O método não é aceite neste caminho. | Veja o cabeçalho `Allow`. |
| 409 | `conflict` | A operação não se pode fazer no estado actual. A razão vem em `details.reason`. | Veja a razão e corrija. |
| 409 | `account_email_domain` | O pedido mexe no correio do domínio do e-mail da conta, ou de um utilizador dela: caixas, reencaminhadores, conta geral, MX ou nameservers. | Faça a alteração no portal da conta. |
| 409 | `idempotency_conflict` | A `Idempotency-Key` foi usada noutro pedido, ou o primeiro pedido ainda está em curso. | Veja [Repetições](https://docs.interweb.ao/pt/api-rules.md). |
| 422 | `validation_failed` | Alguns dados não são válidos. | Corrija os dados, com ajuda de `details`. |
| 429 | `rate_limited` | Passou o limite de pedidos. | Espere o tempo de `Retry-After`. Veja [Limites](https://docs.interweb.ao/pt/api-rules.md). |
| 500 | `internal_error` | Falha do nosso lado. | Tente mais tarde e indique o `correlation_id` ao suporte. |
| 502 | `upstream_error` | O serviço por trás da API não respondeu como esperado. | Tente mais tarde e indique o `correlation_id` ao suporte. |
| 503 | `disabled` | A API está desligada neste momento. | Tente mais tarde. |

### Repetir ou não repetir

- **Vale a pena repetir, com espera:** `429`, `500`, `502` e `503`.
- **Não vale a pena repetir sem mudar nada:** todos os outros.

Num pedido `POST`, envie sempre [`Idempotency-Key`](https://docs.interweb.ao/pt/api-rules.md) logo na primeira tentativa e repita com o mesmo valor.

### Comunicar um problema

Indique ao suporte o `correlation_id`, a hora do pedido e a operação. Nunca envie a chave: o suporte não precisa dela.

## Limites

### Limites de pedidos

| Quem pede | Limite |
|---|---|
| Com chave válida | 90 pedidos por minuto, por chave |
| Toda a conta, somando as chaves | 300 pedidos por minuto |
| Consultar nomes de domínio | 30 por minuto, por conta |
| Alterar domínios, DNS, ciclo de renovação e SMS e fechar tickets (limite comum) | 20 por minuto, por conta |
| Comprar domínios e produtos extra e pagar facturas (limite comum) | 5 por minuto, por conta |
| Ler nameservers, bloqueio, contactos e zona DNS | 30 por minuto, por conta; as respostas vindas da cópia de 60 segundos não contam |
| Pedir o código de transferência | 3 por hora, por conta |
| Abrir tickets | 10 por hora, por conta |
| Responder a tickets | 30 por hora, por conta |
| Descarregar o PDF de uma factura | 20 por minuto, por conta |
| Pesquisar na Base de Conhecimento | 30 por minuto, por conta |
| Pedir um cancelamento | 5 por hora, por conta |
| Sem chave válida | 30 pedidos por minuto, por IP |

Estes são os valores actuais e podem mudar. Nos seus programas, leia os cabeçalhos em vez de fixar os números. `GET /v1/ping` e `GET /v1/openapi.json` contam sempre por IP, mesmo com chave.

### Cabeçalhos

As respostas trazem:

| Cabeçalho | O que é |
|---|---|
| `X-RateLimit-Limit` | Pedidos permitidos por minuto. |
| `X-RateLimit-Remaining` | Pedidos que restam neste minuto. |
| `X-RateLimit-Reset` | Quando acaba o minuto, em segundos Unix. |

A operação [`GET /v1/limits`](https://docs.interweb.ao/pt/key-status.md) mostra os mesmos valores, mais o limite de gastos da chave.

### Quando passa o limite

A API responde `429` com o código `rate_limited` e o cabeçalho `Retry-After`, que indica quantos segundos deve esperar.

- Espere pelo menos esse tempo antes de repetir.
- Se o `429` se repetir, aumente a espera a cada tentativa.
- Evite ciclos de consulta muito rápidos.

### Tamanho do pedido

O corpo de um pedido pode ter até 1048576 bytes (1 MB).

## Paginação

### Parâmetros

| Parâmetro | O que é |
|---|---|
| `page` | O número da página. A primeira é a 1. |
| `per_page` | Quantos resultados por página, de 1 a 100. Por omissão, 10. |

Exemplo do que se junta ao endereço:

```text
?page=2&per_page=50
```

### Resposta

Os resultados vêm em `data`, e `meta` indica a página e o total:

```json
{
  "data": [],
  "meta": {
    "page": 2,
    "per_page": 50,
    "total": 120,
    "total_pages": 3
  }
}
```

| Campo | O que é |
|---|---|
| `page` | A página devolvida. |
| `per_page` | Resultados por página. |
| `total` | Resultados no total. |
| `total_pages` | Páginas no total. |

### Ler todas as páginas

Comece em `page=1` e continue enquanto `page` for menor do que `total_pages`. Cada página conta como um pedido para os [limites](https://docs.interweb.ao/pt/api-rules.md).

## Repetições (Idempotency-Key)

> **Nota:**
>
> Aplica-se ao envio de SMS, [`POST /v1/sms/messages`](https://docs.interweb.ao/pt/sms.md), e às compras de domínios, onde é obrigatória. As operações que criam ou cobram seguem todas estas regras.

### Para que serve

Se a ligação falhar a meio de um pedido, não sabe se ele chegou a ser feito. Com o cabeçalho `Idempotency-Key`, pode repetir o pedido sem risco de registar ou cobrar duas vezes.

### Como usar

Gere um valor único para cada operação e envie-o num pedido `POST`:

```text
Idempotency-Key: 0f8fad5b-d9cb-469f-a165-70867728950e
```

O valor pode ter até 255 caracteres visíveis. Um UUID serve bem. Repita o mesmo valor só quando repetir a mesma operação.

### O que acontece

O valor fica reservado para cada chave durante 24 horas.

| Situação | Resposta |
|---|---|
| Primeiro pedido com este valor | A operação é feita normalmente. |
| Mesmo valor e mesmo corpo | Devolve a resposta guardada, com o cabeçalho `Idempotent-Replayed: true`. Nada é feito outra vez. |
| Mesmo valor e outro corpo | `409` com o código `idempotency_conflict`. |
| Mesmo valor, com o primeiro pedido ainda em curso | `409` com o código `idempotency_conflict`. |

### Depois de uma falha

- **Se não recebeu resposta:** repita o pedido com o mesmo valor.
- **Se recebeu `409` porque o primeiro ainda está em curso:** espere um pouco e repita.
- **Se recebeu `409` porque o corpo é outro:** use um valor novo, se for mesmo uma operação diferente.

## Sandbox e Produção

### Dois modos

O endereço é o mesmo nos dois modos: é a chave que decide.

| | Sandbox (`sandbox_`) | Produção (`prod_`) |
|---|---|---|
| Leituras | Dados verdadeiros da conta | Dados verdadeiros da conta |
| Escritas | Simuladas | Alteram a conta |
| Cobranças | Nunca | Sim, dentro do [limite de gastos](https://docs.interweb.ao/pt/permissions.md) |

> **Atenção:**
>
> Uma chave `sandbox_` lê dados verdadeiros da sua conta. Guarde-a com o mesmo cuidado com que guarda uma chave `prod_`.

### O que a resposta diz

- Todas as respostas com chave trazem o cabeçalho `X-API-Mode`, com `sandbox` ou `production`.
- As escritas simuladas trazem também `X-API-Simulated: true`.
- Enquanto a API está em preparação, nem as chaves `prod_` alteram a conta nem cobram: as escritas são simuladas e o campo `writes_simulated` de [`GET /v1/token`](https://docs.interweb.ao/pt/key-status.md) vem a `true`.
- As chaves criadas durante a preparação, de qualquer modo, são revogadas quando a API abrir, e o dono da conta recebe um aviso por e-mail. Depois disso, crie chaves novas.

### Saber o modo da chave

O campo `mode` da operação [`GET /v1/token`](https://docs.interweb.ao/pt/key-status.md) diz `sandbox` ou `production`.

Para garantir que um programa nunca corre com a chave errada, envie o cabeçalho `X-API-Mode` no pedido. Se não coincidir com o modo da chave, a API recusa com `invalid_request` e a razão `mode_mismatch`.

### Playground

Cada operação, na página da sua área, tem o botão Playground, para fazer pedidos a partir do navegador, sem sair da página.

- A chave que escrever fica só na memória dessa página: não é guardada nem vai no endereço.
- Use uma chave `sandbox_`. As chaves `prod_` agem na sua conta.

### Passar para Produção

Quando o programa estiver pronto, crie uma chave `prod_` com as permissões mínimas, na página [API](https://www.meu.interweb.ao/api-center.php?language=portuguese&currency=1). O prefixo é a única diferença no pedido.