Limits and errors

What is counted, what is capped, and what an error looks like.

Events a month

A plan belongs to your account, and every project on it draws on the same month. A plan is a number of events a month, and a page view counts as an event. Each call to /v1/log counts as one, including backfills, and so does each page view from the browser script, each view of a link page and each click on one. Identify, group and insight calls are not counted. A newsletter signup is not counted either; the New subscriber event it posts to the feed is one event.

The month runs on UTC and resets on the 1st. Nothing already stored is lost when an account runs out. What changes is what it can read:

  • Within the allowance, every event and page view is stored and shown.
  • Past the allowance, new events and page views are still taken in and answered with 201, but they are held: stored, not shown in the feed, charts, exports or the API. The feed says that one arrived, in which channel and when, and never what it says. What is held is let out, whole and with its own times, when the account moves to a plan with room for it (events first, the oldest first), or when the month is over.
  • The first month a paid account goes over, nothing is held. Each account gets this once. A trial that goes over is held at once.
  • At twice the allowance, new events and page views are refused with 429 until the 1st or until the account moves to a bigger plan. Refused ones are not counted.

A new account is on trial for 7 days, with what the smallest plan allows. Once the trial is over, or a subscription ends, and the account has no plan, its events and page views are still taken in and held for 7 more days, up to twice what the trial allowed. After that they are refused with 402 until it has a plan. What was held is let out as soon as the account chooses one.

Sizes

Limit
Channel name 64 characters: lowercase letters, digits and dashes
Event name 200 characters
Description 4,000 characters
Tags on an event, properties on a person 50
A tag or property key 64 characters
A tag or property value 1,000 characters
Properties kept on one person or group, across calls 100
user_id, group_id and previous_id 200 characters
timestamp Between 1970 and five minutes from now. With a public key, within the last 7 days
A request body 256 KB
Push notifications from one project 60 a minute; events past that are stored without one
Events per read request 100
A range for charts and funnels 366 days
Steps in a funnel 2 to 6
Requests with a public key 120 a minute from one address

Errors

An error is JSON with a sentence that says what to fix:

{ "error": "\"channel\" is required: lowercase letters, digits and dashes, up to 64 characters." }

The same sentence is also under message and under validation.body[0].message, for clients that look there.

Status Means
400 Something in the request is wrong. The sentence says what.
401 The key is missing or unknown.
403 The key is real but may not do this: a public key reading, a read key writing, or a channel outside the key’s limit.
404 No such person, event or key.
402 The account has no plan, and its events are no longer held: the 7 days after the trial or subscription ended are over, or it has sent twice what the trial allowed.
413 The body is larger than 256 KB.
429 The account has sent twice its month’s events and page views, or a public key is sending too fast.

A 4xx will fail the same way if sent again. A 5xx or a dropped connection is worth one retry, which the SDKs do for you.