Limites e erros
Limites por minuto, formato de erro, códigos de motivo, paginação e idempotência.
Atualizado em 10 de outubro de 2026
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")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.
{
"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_fromedays(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.jsonconst 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.