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

# Limites e Erros

> Códigos de erro, rate limits e como tratar respostas da API

# Limites e Erros

## Códigos HTTP padronizados

| Status | Significado                                              | Ação recomendada                  |
| ------ | -------------------------------------------------------- | --------------------------------- |
| `200`  | Sucesso                                                  | —                                 |
| `201`  | Recurso criado                                           | —                                 |
| `204`  | Sucesso sem corpo                                        | —                                 |
| `400`  | Body inválido ou recurso ausente                         | Validar payload                   |
| `401`  | Token inválido, ausente ou expirado                      | Gerar novo PAT                    |
| `403`  | Sem permissão no recurso ou domínio bloqueado pelo plano | Verificar papel na org / upgrade  |
| `404`  | Recurso não encontrado                                   | Conferir IDs                      |
| `409`  | Conflito (ex: nome duplicado)                            | Resolver conflito                 |
| `429`  | Rate limit ou limite de plano atingido                   | Backoff / upgrade                 |
| `500`  | Erro interno do Portal                                   | Tente novamente / contato suporte |
| `501`  | Serviço não implementado para aquela integração          | Use outro serviço                 |

## Formato padrão dos erros

A maioria dos erros segue o formato:

```json theme={null}
{
  "error": "codigo_legivel",
  "message": "Descricao humana do que aconteceu"
}
```

Códigos comuns:

| `error`             | Quando ocorre                         |
| ------------------- | ------------------------------------- |
| `forbidden`         | Sem permissão na entidade/recurso     |
| `domain_restricted` | Plano não libera aquele domínio       |
| `limit_reached`     | Atingiu limite de quantidade do plano |
| `not_found`         | Recurso ausente                       |
| `invalid_body`      | JSON malformado ou campos faltando    |

Exemplo de `limit_reached`:

```json theme={null}
{
  "error": "limit_reached",
  "message": "Limite de entidades expostas atingido (5)",
  "limit": 5,
  "current": 5
}
```

## Limites por plano

| Recurso                           | Free    | Padrão    |
| --------------------------------- | ------- | --------- |
| Integrações                       | 1       | Ilimitado |
| Automações                        | 2       | Ilimitado |
| Entidades expostas (Alexa/Google) | 5       | Ilimitado |
| Domínios controlados              | `cover` | Todos     |

Veja a tabela completa em [Referência → Limites por Plano](/referencia/limites-por-plano).

## Rate limiting

A API protege os endpoints contra abuso. Em caso de excesso, você recebe `429 Too Many Requests`. Recomendacoes:

* **Throttle no cliente**: não envie rajadas de chamadas — espalhe no tempo.
* **Backoff exponencial** ao receber 429: dobre o intervalo a cada tentativa.
* **Use WebSocket** para receber estados em tempo real em vez de polling agressivo.

```python theme={null}
import time
import requests

def call_with_backoff(method, url, **kwargs):
    delay = 1
    for attempt in range(6):
        resp = requests.request(method, url, **kwargs)
        if resp.status_code != 429:
            return resp
        time.sleep(delay)
        delay *= 2
    return resp
```

## Erros específicos do `POST /v1/service`

| Status | Body                                    | O que significa                                   |
| ------ | --------------------------------------- | ------------------------------------------------- |
| `400`  | `Entidade ausente light`                | `entity_id` não existe ou não pertence ao usuário |
| `403`  | `{ "error": "forbidden" }`              | Org member sem `can_control` na entidade          |
| `403`  | `{ "error": "domain_restricted" }`      | Plano não libera aquele domínio                   |
| `501`  | `Service not found: light.turn_rainbow` | O serviço não existe nessa integração             |

## Depurando

1. **Confira a especificação**: [API Reference](/api-reference) lista todos os endpoints com schemas.
2. **Verifique o token**: faca uma chamada simples (`GET /v1/states`) — se voltar 401, o problema e o token.
3. **Verifique o contexto da org**: se opera em organização, o header `X-Organization-Id` precisa estar correto e o usuário precisa ser membro.
4. **Logs do painel**: em **Automações → Histórico** você ve cada execução com trace passo-a-passo.

<Tip>
  Em caso de comportamento inesperado, abra um ticket em [suporte.unicontrol.com.br](https://suporte.unicontrol.com.br) com a request\_id retornada nos headers da resposta (`X-Request-Id`).
</Tip>