# Chaves e níveis de acesso

> Chaves publicáveis e secretas, o modo de teste, os níveis de acesso, os limites por minuto e os erros da API do ByDomu.


Cada requisição leva a chave no cabeçalho `X-API-Key`. Você as cria no ByDomu, em Configurações › API e webhooks; a completa aparece uma só vez.

## Publicáveis e secretas

**Publicável** `domu_pk_live_`

Para seu site e o navegador: pode ir no código da página.

portal:read · leads:write · booking:write · finder:write · events:write

Só o público e receber clientes.

**Secreta** `domu_sk_live_`

Só de um servidor: Zapier, Make, n8n, seu backend ou um cliente MCP.

Qualquer permissão: *:read e, com aprovação, *:write

Em um navegador responde 403.

As chaves antigas (`domu_live_`) continuam funcionando igual enquanto as revisamos.

## Modo de teste

As chaves de teste (`domu_sk_test_` e `domu_pk_test_`) têm todas as permissões sem solicitar acesso e só veem sua organização de teste, com dados de exemplo: nada do que você fizer com elas chega aos seus clientes. Limite: 100 requisições e 30 escritas por minuto.

[Guia do modo de teste](https://developers.bydomu.com/pt/guias/modo-de-prueba)

## Níveis de acesso

O que uma chave pode fazer depende do plano e do que o suporte aprovar. Nunca há API durante o teste grátis nem com o e-mail sem verificar.

Nível Planos Como se obtém

1 **Chaves publicáveis** 300 requisições e 60 escritas por minuto · até 5 chaves Qualquer plano pago Sem solicitação

2 **Secretas somente leitura** 60 requisições por minuto · até 2 chaves Business · Enterprise Automático

3 **Escritas, mensagens, webhooks e limites altos** Sob medida do aprovado Qualquer plano pago Revisão do suporte

Mais limite ou mais permissões são pedidos em Configurações › API e webhooks.

## Limites e paginação

Cada resposta diz quanto resta do minuto. As listas são paginadas com `page` e `pageSize` e trazem `meta.total` e `meta.totalPages`.

**Cabeçalhos de resposta**

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 41
Retry-After: 41            # só com 429
Idempotency-Status: replayed  # nova tentativa com a mesma Idempotency-Key
```

## Erros

Sempre com o mesmo formato: `{ "error": { "code", "message" } }`.

**400** `VALIDATION_ERROR` Dados de entrada inválidos

**401** `UNAUTHORIZED` Chave ausente ou inválida

**402** `PAYMENT_REQUIRED` Conta somente leitura: escrita recusada

**403** `FORBIDDEN` A chave não tem essa permissão

**403** `SECRET_KEY_IN_BROWSER` Chave secreta usada em um navegador

**403** `API_ACCESS_REQUIRED` O nível da conta não permite esta chave

**403** `PLAN_LIMIT_REACHED` Um limite do plano foi atingido

**404** `NOT_FOUND` Recurso não encontrado

**409** `IDEMPOTENCY_CONFLICT` Idempotency-Key reutilizada com outro corpo

**409** `IDEMPOTENCY_IN_PROGRESS` Outra requisição com a mesma Idempotency-Key ainda está em andamento

**429** `RATE_LIMITED` Limite por minuto excedido

**429** `TENANT_RATE_LIMITED` Limite de escritas por minuto da organização excedido