Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mivicall.com/llms.txt

Use this file to discover all available pages before exploring further.

A API Mivicall aplica rate limits por API key e por IP para garantir estabilidade.

Limites default

DimensãoLimiteJanela
Por API key300 requests1 min (sliding)
Por API key30 requests1 segundo (burst)
Por IP100 requests1 min (defensivo)
Webhookssem rate limit(apenas você → vocês)

Headers de resposta

Cada resposta inclui:
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1778649660    # unix timestamp quando reset

HTTP 429 Too Many Requests

Ao exceder, devolvemos:
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Reset: 1778649672
Content-Type: application/json

{
  "error": "rate_limit_exceeded",
  "message": "API key exceeded 300 req/min. Retry in 12 seconds.",
  "retryAfter": 12
}

Backoff recomendado

Exponential backoff com jitter, idêntico ao do AWS SDK:
async function callWithBackoff(fn: () => Promise<Response>, maxRetries = 6) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fn()
    if (res.status !== 429) return res

    const retryAfter = Number.parseInt(res.headers.get('Retry-After') ?? '1', 10)
    const jitter = Math.random() * 1000
    const wait = Math.min(retryAfter * 1000 + jitter, 60_000) // cap 1min
    await new Promise(r => setTimeout(r, wait))
  }
  throw new Error('rate_limit: max retries exceeded')
}

Aumentar limites

Para integrações de alto volume (>5 clínicas-cliente, >10k requests/dia), contactem support@mivicall.com com:
  • API key prefix
  • Volume estimado
  • Caso de uso
Aumentos são gratuitos para vendors com 5+ clientes activos.

Caching recomendado

Para reduzir hits ao rate limit:
RecursoTTL sugeridoNotas
GET /v1/tenants/me5 minConfig muda raramente
GET /v1/professionals1 horaEquipa estável
GET /v1/services1 horaIdem
GET /v1/appointments?from=X&to=Y30sLista da agenda
GET /v1/appointments/:idsem cachePode ter mudado de status
Usem o header If-None-Match com ETag para 304 Not Modified (implementação em roadmap).