Skip to main content

​
Rate limits

Limits apply per token (not per user, not per IP) — every integration gets its own independent quota.
WindowLimit
Per minute60 requests
Per hour1,000 requests
If you cross either limit: 
HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "message": "ThrottlerException: Too Many Requests",
  "statusCode": 429
}
Need more throughput (e.g. bulk-syncing a CRM with hundreds of thousands of contacts)? Email support@keebai.com with your expected volume and we’ll bump the cap.

​
How to handle 429 properly

Use exponential backoff with jitter. Pseudocode: 
async function callKeebaiWithRetry(path: string, attempt = 0): Promise<Response> {
  const response = await fetch(`https://api.keebai.com/v1${path}`, {
    headers: { Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}` },
  });

  if (response.status === 429 && attempt < 5) {
    const baseDelay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s, 8s, 16s
    const jitter = Math.random() * 500;
    await new Promise((r) => setTimeout(r, baseDelay + jitter));
    return callKeebaiWithRetry(path, attempt + 1);
  }

  return response;
}
Don’t tight-loop retries — you’ll ban yourself and balloon your own latency.

​
Error format

Every error follows the standard NestJS shape: 
{
  "message": "<human description>",
  "error": "<category>",
  "statusCode": <HTTP number>
}
StatusCategoryWhen
400 Bad RequestBad RequestInvalid body, malformed query params, schema validation failed.
401 UnauthorizedUnauthorizedToken invalid, missing, revoked, or expired. See Authentication.
403 ForbiddenForbiddenToken is valid but lacks the required scope. See Scopes.
404 Not FoundNot FoundResource or route doesn’t exist.
429 Too Many RequestsThrottlerYou hit the rate limit.
500 Internal Server ErrorInternal Server ErrorServer-side bug. If it persists, report it.
503 Service UnavailableService UnavailableMaintenance or temporary degradation. Retry with backoff.

​
Best practices

Idempotency

Design retries to be safe. GET and DELETE are idempotent out of the box; for POST/PATCH, dedupe on your side with stable identifiers.

Sensible timeouts

Set a client timeout between 10 and 30 seconds. Lower kills legitimate requests; higher locks your thread on transient slowness.

Log everything useful

Log status, request id (when the API returns one in headers), and duration. Future-you will thank you.

Circuit breaker

On repeated 5xx, pause requests for a few seconds. Your system stays up for everything else that doesn’t depend on Keebai.

​
In production

  • Monitor latency, error rate, and status codes. An alert on error rate >5% catches issues before users do.
  • Rotate tokens every 90 days, incident or not. Mint, deploy, validate, revoke the old.
  • Audit Last used in the tokens table periodically. Tokens unused for months are revoke candidates.
  • Suspect us? Email support@keebai.com.