Errors and rate limits

Errors carry a detail field. Read that; do not parse prose out of the status line.

{
  "detail": "Bot not found or access denied."
}

Validation failures return 422 with detail as a list of field-level problems. Feature-gated endpoints return a machine-readable code alongside the message, the same shape whether the gate is a plan feature or an exhausted credit balance:

{
  "detail": {
    "error": "feature_not_available",
    "feature": "lead_intelligence",
    "message": "Lead export is included on Starter and above."
  }
}

{
  "detail": {
    "error": "insufficient_credits",
    "required": 1,
    "available": 0,
    "message": "You're out of credits. Upgrade your plan or buy a top-up to keep chatting."
  }
}

Limits are per endpoint and are counted against your API key, your bot key, or the caller's IP depending on the endpoint. Expensive operations are limited harder than reads.

{
  "detail": "Too many requests. Please slow down and try again shortly.",
  "error": "Rate limit exceeded",
  "retry_after_seconds": 24
}

• Honour Retry-After on a 429 rather than guessing a backoff.
• Retry 5xx with exponential backoff and jitter. Do not retry 4xx other than 429.
• Keep write requests idempotent on your side, so a retry after a timeout cannot double-apply.
• Prefer webhooks over polling. A webhook costs you nothing against your rate limits and arrives sooner.