lindy-rate-limits by jeremylongshore

---
name: lindy-rate-limits
description: 'Manage Lindy AI credits, rate limits, and usage optimization.

  Use when hitting rate limits, optimizing credit consumption,

  or implementing usage controls.

  Trigger with phrases like "lindy rate limit", "lindy credits",

  "lindy quota", "lindy throttling", "lindy API limits".

  '
allowed-tools: Read, Write, Edit
version: 1.20.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- lindy
- api
compatibility: Compatible with AI coding agents that can read Markdown and review application code
---
# Lindy Rate Limits and Credits

## Overview

Build application-side controls for Lindy webhook-trigger traffic and workspace
usage. Lindy plan terms, prices, credit rules, and service limits can vary or
change; obtain them from the current workspace and contract instead of copying
fixed commercial numbers into code.

Use **Read** to inspect the caller and **Write** or **Edit** to implement its policy.
This skill does not assume an undocumented Lindy REST API or SDK.

## Prerequisites

- The exact webhook URL generated by the target Lindy trigger.
- A nonempty secret generated for that trigger and stored in a secret manager.
- Current workspace or contract evidence for credits, quotas, and entitlements.
- A shared atomic store for admission control and idempotency when more than one
  process or instance can send triggers.
- A durable queue with dead-letter handling for work that may need retries.
- An approved bounded payload schema and a synthetic, non-sensitive test case.

## Instructions

### Step 1: Establish current limits and a local safety policy

Record the evidence source and review date for every Lindy-provided credit or
service constraint. Then choose application-owned controls independently:

- maximum admitted events per tenant and workload;
- maximum queue depth and age;
- maximum serialized payload size;
- retry count and total retry deadline;
- concurrency per worker pool; and
- warning, shedding, and stop thresholds.

These are local risk controls, not claims about Lindy's service limits. Review
them from observed traffic, task outcomes, and the organization's budget.

### Step 2: Fail closed before attaching the trigger secret

Parse the configured URL; require protocol `https:`, hostname exactly
`public.lindy.ai`, no username or password, and the expected webhook path. Reject
an empty trigger secret. Never send the trigger secret to a callback receiver or
reuse a callback secret for the outbound trigger.

```typescript
const triggerUrl = new URL(process.env.LINDY_TRIGGER_URL ?? '');
const triggerSecret = process.env.LINDY_TRIGGER_SECRET ?? '';

if (
  triggerUrl.protocol !== 'https:' ||
  triggerUrl.hostname !== 'public.lindy.ai' ||
  triggerUrl.username !== '' ||
  triggerUrl.password !== '' ||
  !triggerUrl.pathname.startsWith('/api/v1/webhooks/')
) {
  throw new Error('Refusing to send a trigger secret outside the expected Lindy webhook URL');
}
if (triggerSecret.length === 0) throw new Error('LINDY_TRIGGER_SECRET is required');
```

### Step 3: Validate and deduplicate before enqueue

Allow only documented fields, types, lengths, and enumerated values. Reject
unknown fields and payloads above the locally chosen byte limit. Require a stable
`requestId` from the business event.

Atomically reserve that ID in a shared idempotency store before enqueueing. Put
the validated event into a durable queue and reuse the same ID for every retry.
Do not assume an `Idempotency-Key` header is honored by Lindy; the caller owns the
deduplication ledger unless current Lindy documentation explicitly proves otherwise.

### Step 4: Throttle across the whole deployment

Use an atomic token bucket, leaky bucket, or concurrency semaphore in the shared
store, keyed by the isolation boundary such as tenant plus agent. A process-local
counter protects only one process and is insufficient for horizontally scaled or
serverless callers.

The safe path is:

```text
bounded input -> shared idempotency claim -> durable queue
              -> shared admission control -> webhook worker -> outcome ledger
```

When capacity is unavailable, leave the event queued or reject it explicitly.
Do not busy-loop or allow every instance to retry independently.

### Step 5: Check responses and retry only transient outcomes

- Treat a 2xx response as transport acceptance, not proof of completed work.
- Treat authentication and other non-retryable 4xx responses as permanent failure.
- Retry only explicitly transient outcomes such as 408, 429, or selected 5xx
  responses, with capped exponential backoff and jitter.
- Honor a valid `Retry-After` only up to the local maximum delay.
- Bound attempts and total elapsed time; dead-letter the event when exhausted.
- Record status class, attempt, latency, and request ID, never the secret or full
  payload.
- Corroborate successful task creation in the Lindy Tasks view or through an
  authenticated callback carrying the same request ID.

The detailed reference includes a secure TypeScript worker and shared-store
contract: [implementation details](references/implementation.md).

### Step 6: Monitor and tune from evidence

Track admitted, queued, shed, retried, dead-lettered, and corroborated events;
queue age; response status classes; and workspace usage from available Lindy
views. Alert on a sustained change from the observed baseline. Revisit the local
policy whenever the plan, workspace configuration, workload, or deployment shape
changes.

## Output

Produce a rate-control design containing:

- dated sources for current Lindy constraints and credit information;
- the local admission, payload, concurrency, queue, and retry policy;
- exact trust boundaries for trigger and callback secrets;
- bounded schema and shared idempotency key design;
- durable-queue, shared-throttling, and dead-letter behavior;
- response classification and task-corroboration rules;
- dashboards, alerts, owners, and review cadence; and
- test evidence for duplicates, bursts, transient failures, permanent failures,
  worker restarts, and multi-instance contention.

## Examples

### Policy record without invented service limits

```yaml
evidence:
  lindy_constraints: workspace billing and task views reviewed on YYYY-MM-DD
local_policy:
  payload_schema: trigger-event-v2
  payload_bytes: organization-approved bound
  admission_key: tenant_id + agent_id
  idempotency_key: source_event_id
  retryable_statuses: [408, 429, selected_5xx]
  terminal_action: dead_letter_and_alert
verification:
  task_creation: correlate requestId in the Lindy Tasks view
```

### Duplicate-delivery test

Submit the same synthetic `requestId` concurrently through two application
instances. Pass only when one durable job is created, at most one webhook attempt
is admitted for that business event, and the duplicate outcome is observable.

## Error Handling

| Condition | Required behavior |
|---|---|
| URL is not HTTPS on exact `public.lindy.ai` host | Reject before attaching the trigger secret |
| Secret is empty | Fail startup or configuration validation |
| Payload is unknown, malformed, or oversized | Reject before idempotency claim or enqueue |
| Duplicate request ID | Return the recorded disposition; do not repeat the side effect |
| 401/403 or other permanent 4xx | Stop retrying, redact logs, alert the owner |
| 408/429/selected 5xx | Apply bounded backoff with jitter, then dead-letter |
| Shared store unavailable | Fail closed or keep work durable; do not fall back silently to per-process limits |
| 2xx without task corroboration | Mark accepted but unverified and investigate |

## Resources

- [Lindy webhook trigger documentation](https://docs.lindy.ai/skills/by-lindy/webhooks)
- [Lindy HTTP Request action documentation](https://docs.lindy.ai/skills/by-lindy/http-request)
- [Implementation guide](references/implementation-guide.md)
- [Detailed worker pattern](references/implementation.md)