Pular para o conteúdo

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.

ChamadaLimite
Simular (bookings:quote)30 por minuto
Criar, cancelar e remarcar20 por minuto
Gerar novo Pix (repay)10 por minuto
MCP, requisições HTTP60 por minuto por IP
MCP, agendamentos confirmados5 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");
}

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": []
  }
}
CampoO que é
codeClasse do erro, como INVALID_ARGUMENT, NOT_FOUND ou RATE_LIMITED.
reasonMotivo exato, do catálogo abaixo.
messageTexto em português para a pessoa que está agendando.
detailsLista 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.

StatusreasonO que significaO que fazer
400INVALID_REQUESTAlgum campo está faltando ou fora do formato; details aponta quais.Corrija os campos de details e envie de novo.
400PAST_TIMEO horário escolhido já passou.Consulte os horários livres e escolha um start_at futuro.
401BOOKING_TOKEN_INVALIDO 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.
404SHOP_NOT_FOUNDO negócio não existe, não está listado ou está inativo.Busque de novo e use o slug devolvido pela busca.
404BOOKING_NOT_FOUNDNão há reserva com esse id neste negócio.Confira o id e o slug da reserva.
404RESOURCE_NOT_FOUNDO 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.
409SLOT_UNAVAILABLEO 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.
409OPEN_PAYMENTS_LIMITO cliente já tem reservas aguardando o Pix neste negócio.Pague ou cancele uma delas antes de reservar outra.
409BOOKING_NOT_ACTIVEA reserva já foi cancelada, concluída ou encerrada e não aceita essa ação.Consulte a reserva para ver a situação atual.
409BOOKING_EXPIREDO 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.
409IDEMPOTENCY_KEY_REUSEDA 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.
422QUOTE_MISMATCHOs 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.
422QUOTE_EXPIREDA simulação (quote_id) passou de 15 minutos.Simule de novo e confirme com o cliente.
422CANCEL_WINDOW_CLOSEDO prazo de cancelamento do negócio já passou.O cliente precisa falar com o negócio (get_business / perfil traz o contato).
422RESCHEDULE_WINDOW_CLOSEDO prazo de remarcação do negócio já passou.O cliente precisa falar com o negócio.
422BUSINESS_RULEOutra regra do negócio impede a ação; a message explica em português.Mostre a message ao cliente.
429RATE_LIMITEDMuitas 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çãoRespostaO que fazer
Busca sem resultado200 com data: [] (REST) e businesses: [] (MCP)Tente sem q, só com cidade e segmento.
Sem horário livre no intervalo200 com os dias e slots: []Consulte outro intervalo ou outro profissional.
Sinal por Pix exigido201 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

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.

Limites e erros · API e MCP · Agendria