The effective limit

Your org's effective monthly limit is the per-org override if one is set, otherwise the limit that comes with your plan:

effective_limit = org_override ?? plan_limit

• Plan limit — each plan carries a monthly_item_limit. A null plan limit means unlimited. The beta plan is capped at 1,000 items / month; an org that exceeds it receives a 429 until the window resets.
• Per-org override — an org can be given an explicit limit that wins over its plan. A null override means "inherit the plan." The effective limit is null (unlimited) only when both the override and the plan limit are null.

The counting window

Usage is counted per calendar month in UTC. The window opens at 00:00:00Z on the first of the month and the count resets to zero at the start of the next month. It is not a rolling 30-day window and it is not anchored to your signup date.

When the quota is exceeded

Once the org is at or over its effective limit, /api/queue returns 429 and the item is not queued. The stable response body is:

// HTTP 429 — the org is at or over its monthly quota; the item was NOT queued
{
  "error": "monthly quota exceeded",
  "limit": 1000,
  "used":  1000,
  "plan":  "free"
}

Asenta additionally returns a Retry-After header on the 429 (and, where available, reset_at and upgrade_url hints) so your client can back off until the window resets and prompt an upgrade. Treat the { error, limit, used, plan } body as the stable contract and read the extra signals when present.

Handling a 429 in your pipeline

A quota 429 is not a transient failure to hammer-retry — the window only rolls over at the start of the next UTC month. Detect the status, stop submitting, and surface it (raise the plan limit, or queue the work locally until the window resets):

const res = await fetch("https://yourapp.com/api/queue", {
  method: "POST",
  headers: {
    "x-checkpoint-key": process.env.CHECKPOINT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ content, confidence, segment }),
});

if (res.status === 429) {
  const { limit, used, plan } = await res.json();
  // The item was NOT accepted. Do not treat this as a transient error to
  // hammer-retry: the window only resets at the start of the next calendar
  // month (UTC). Back off, alert, and consider raising the plan limit.
  const retryAfter = res.headers.get("Retry-After"); // seconds, when present
  console.warn(`Quota hit on plan "${plan}": ${used}/${limit}. Retry-After=${retryAfter}`);
  return;
}