# Claves y niveles de acceso

> Claves publicables y secretas, el modo de prueba, los niveles de acceso, los límites por minuto y los errores de la API de ByDomu.


Cada petición lleva la clave en el encabezado `X-API-Key`. Las creas en ByDomu, en Configuración › API y webhooks; la completa se ve una sola vez.

## Publicables y secretas

**Publicable** `domu_pk_live_`

Para tu página web y el navegador: puede ir en el código de la página.

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

Solo lo público y recibir clientes.

**Secreta** `domu_sk_live_`

Solo desde un servidor: Zapier, Make, n8n, tu backend o un cliente MCP.

Cualquier permiso: *:read y, con aprobación, *:write

Desde un navegador responde 403.

Las claves de antes (`domu_live_`) siguen funcionando igual mientras las revisamos.

## Modo de prueba

Las claves de prueba (`domu_sk_test_` y `domu_pk_test_`) tienen todos los permisos sin solicitar acceso y solo ven tu organización de prueba, con datos de ejemplo: nada de lo que hagas con ellas llega a tus clientes. Límite: 100 peticiones y 30 escrituras por minuto.

[Guía del modo de prueba](https://developers.bydomu.com/guias/modo-de-prueba)

## Niveles de acceso

Lo que puede hacer una clave depende del plan y de lo que apruebe soporte. Nunca hay API durante la prueba gratis ni con el correo sin verificar.

Nivel Planes Cómo se obtiene

1 **Claves publicables** 300 peticiones y 60 escrituras por minuto · hasta 5 claves Cualquier plan pagado Sin solicitud

2 **Secretas de solo lectura** 60 peticiones por minuto · hasta 2 claves Business · Enterprise Automático

3 **Escrituras, mensajes, webhooks y límites altos** A la medida de lo aprobado Cualquier plan pagado Revisión de soporte

Más límite o más permisos se piden desde Configuración › API y webhooks.

## Límites y paginación

Cada respuesta dice cuánto te queda del minuto. Los listados se paginan con `page` y `pageSize` y traen `meta.total` y `meta.totalPages`.

**Encabezados de respuesta**

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 41
Retry-After: 41            # solo con 429
Idempotency-Status: replayed  # reintento con la misma Idempotency-Key
```

## Errores

Siempre con la misma forma: `{ "error": { "code", "message" } }`.

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

**401** `UNAUTHORIZED` Clave faltante o inválida

**402** `PAYMENT_REQUIRED` Cuenta en solo lectura: escritura rechazada

**403** `FORBIDDEN` La clave no tiene ese permiso

**403** `SECRET_KEY_IN_BROWSER` Clave secreta usada desde un navegador

**403** `API_ACCESS_REQUIRED` El nivel de la cuenta no permite esta clave

**403** `PLAN_LIMIT_REACHED` Se alcanzó un tope del plan

**404** `NOT_FOUND` Recurso no encontrado

**409** `IDEMPOTENCY_CONFLICT` Idempotency-Key reutilizada con otro cuerpo

**409** `IDEMPOTENCY_IN_PROGRESS` Otra petición con la misma Idempotency-Key sigue en curso

**429** `RATE_LIMITED` Límite por minuto superado

**429** `TENANT_RATE_LIMITED` Límite de escrituras por minuto de la organización superado