---
title: "Limites e erros · API e MCP · Agendria"
description: "Limites por minuto, formato de erro, códigos de motivo, paginação e idempotência."
last_updated: 2026-10-10
canonical: "https://agendria.com.br/desenvolvedores/limites-e-erros"
---

# Limites e erros · API e MCP · Agendria

[Desenvolvedores](/desenvolvedores)

[Referência](/desenvolvedores/referencia)

## Limites

Os limites contam por IP e por negócio, numa janela de um minuto. Passou do limite, a resposta é 429.

| Chamada | Limite |
| --- | --- |
| Simular (bookings:quote) | 30 por minuto |
| Criar, cancelar e remarcar | 20 por minuto |
| Gerar novo Pix (repay) | 10 por minuto |
| MCP, requisições HTTP | 60 por minuto por IP |
| MCP, agendamentos confirmados | 5 a cada 10 minutos |

As respostas não trazem cabeçalho com o saldo do limite. Se vier 429, espere cerca de um minuto e tente de novo, com intervalo crescente.

```
`async function request(url, init, attempts = 4) { for (let i = 0; i < attempts; i++) { const res = await fetch(url, init); if (res.status !== 429 && res.status < 500) return res; await new Promise((r) => setTimeout(r, 2 ** i * 1000 + Math.random() * 250)); } throw new Error("Sem resposta após várias tentativas"); }`
```

```
`import random, time, requests def request(method, url, attempts=4, **kwargs): for i in range(attempts): res = requests.request(method, url, **kwargs) if res.status_code != 429 and res.status_code < 500: return res time.sleep(2**i + random.random() / 4) raise RuntimeError("Sem resposta após várias tentativas")`
```

Precisa de mais?

Integrações com volume maior podem pedir um limite próprio em [contato@agendria.com.br](mailto:contato@agendria.com.br).

## Formato de erro

Todo erro usa o mesmo envelope, na REST e no MCP. Programe por `reason`: ele é estável. A `message` vem em português, pronta para mostrar, e pode mudar.

Resposta 409

```
`{ "error": { "code": "CONFLICT", "reason": "SLOT_UNAVAILABLE", "message": "Esse horário acabou de ser ocupado. Escolha outro.", "details": [] } }`
```

| Campo | O que é |
| --- | --- |
| `code` | Classe do erro, como INVALID_ARGUMENT, NOT_FOUND ou RATE_LIMITED. |
| `reason` | Motivo exato, do catálogo abaixo. |
| `message` | Texto em português para a pessoa que está agendando. |
| `details` | Lista de { field, issue } quando campos estão inválidos. |

## Motivos de erro

O catálogo completo, gerado da mesma fonte que a API e o MCP usam. Cada operação da referência lista os que ela pode devolver.

| Status | reason | O que significa | O que fazer |
| --- | --- | --- | --- |
| 400 | `INVALID_REQUEST` | Algum campo está faltando ou fora do formato; `details` aponta quais. | Corrija os campos de `details` e envie de novo. |
| 400 | `PAST_TIME` | O horário escolhido já passou. | Consulte os horários livres e escolha um `start_at` futuro. |
| 401 | `BOOKING_TOKEN_INVALID` | O token da reserva está ausente, errado ou não é desta reserva. | Use o `manage_token` (REST) ou o `booking_token` (MCP) recebido na criação. |
| 404 | `SHOP_NOT_FOUND` | O negócio não existe, não está listado ou está inativo. | Busque de novo e use o `slug` devolvido pela busca. |
| 404 | `BOOKING_NOT_FOUND` | Não há reserva com esse id neste negócio. | Confira o id e o `slug` da reserva. |
| 404 | `RESOURCE_NOT_FOUND` | O serviço, o profissional ou outro item pedido não existe neste negócio. | Liste os serviços do negócio e use um `id` da lista. |
| 409 | `SLOT_UNAVAILABLE` | O horário foi ocupado, está fora do expediente ou o profissional não está livre. | Consulte os horários livres de novo e escolha outro `start_at`. |
| 409 | `OPEN_PAYMENTS_LIMIT` | O cliente já tem reservas aguardando o Pix neste negócio. | Pague ou cancele uma delas antes de reservar outra. |
| 409 | `BOOKING_NOT_ACTIVE` | A reserva já foi cancelada, concluída ou encerrada e não aceita essa ação. | Consulte a reserva para ver a situação atual. |
| 409 | `BOOKING_EXPIRED` | O Pix do sinal não foi pago no prazo e o horário foi liberado. | Gere um novo Pix com `:repay` (REST) se o horário ainda estiver livre, ou agende de novo. |
| 409 | `IDEMPOTENCY_KEY_REUSED` | A mesma `Idempotency-Key` foi usada com um corpo diferente. | Use uma chave nova para cada pedido novo; repita a mesma chave só para repetir o mesmo pedido. |
| 422 | `QUOTE_MISMATCH` | Os dados enviados não são os da simulação aprovada (`quote_id`). | Simule de novo com os dados corretos e confirme com o cliente. |
| 422 | `QUOTE_EXPIRED` | A simulação (`quote_id`) passou de 15 minutos. | Simule de novo e confirme com o cliente. |
| 422 | `CANCEL_WINDOW_CLOSED` | O prazo de cancelamento do negócio já passou. | O cliente precisa falar com o negócio (`get_business` / perfil traz o contato). |
| 422 | `RESCHEDULE_WINDOW_CLOSED` | O prazo de remarcação do negócio já passou. | O cliente precisa falar com o negócio. |
| 422 | `BUSINESS_RULE` | Outra regra do negócio impede a ação; a `message` explica em português. | Mostre a `message` ao cliente. |
| 429 | `RATE_LIMITED` | Muitas tentativas em pouco tempo. | Espere cerca de um minuto e tente de novo. |

## O que não é erro

Algumas respostas parecem falha, mas são normais. Não trate como erro.

| Situação | Resposta | O que fazer |
| --- | --- | --- |
| Busca sem resultado | 200 com `data: []` (REST) e `businesses: []` (MCP) | Tente sem `q`, só com cidade e segmento. |
| Sem horário livre no intervalo | 200 com os dias e `slots: []` | Consulte outro intervalo ou outro profissional. |
| Sinal por Pix exigido | 201 com `status: pending` e `payment` (Pix copia e cola e `expires_at`) | Pague até `payment.expires_at`; sem pagamento a reserva vira `expired` e o horário é liberado. |

## Paginação

A busca de negócios usa cursor. A resposta traz `page.next_cursor`; envie esse valor em `cursor` para a próxima página e pare quando ele vier vazio. `limit` controla o tamanho da página.

- Não monte o cursor: ele é opaco e pode mudar de formato.
- Horários livres não paginam. Use `date_from` e `days` (de 1 a 31) para andar no calendário.

## Idempotência

Envie `Idempotency-Key` em todo POST que muda algo. Repetir a mesma chave com o mesmo corpo devolve a resposta original, sem agendar duas vezes. A mesma chave com outro corpo dá `IDEMPOTENCY_KEY_REUSED`. Use um UUID por tentativa ou o próprio `quote_id`.

```
`curl -X POST "https://agendria.com.br/api/v1/public/shops/sandbox-agendria/bookings" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d @reserva.json`
```

```
`const key = crypto.randomUUID(); const send = () => fetch(`${base}/shops/sandbox-agendria/bookings`, { method: "POST", headers: { "Content-Type": "application/json", "Idempotency-Key": key }, body: JSON.stringify(body), }); const res = await send().catch(send);`
```

## Cache

Leituras públicas têm cache curto: 60 segundos, e 15 segundos nos horários livres. Confirme o horário logo antes de agendar. A simulação nunca usa cache.

## Sitemap

Veja o [mapa do site](https://agendria.com.br/sitemap.md) com todas as páginas em Markdown.
