Errors

Every error is one shape:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key does not have access to that site."
  }
}

code is a symbolic string, not a repeated HTTP status. Branch on code — it is stable, and it distinguishes cases that share a status.

message is for humans. It never contains anything from your request — no field name, no value, no site id. That is deliberate: an endpoint that echoes input back is both a way to inject content and a way to probe. Do not parse it.

400 — the request is malformed

The message names what was wrong and, where there is a fixed set, lists it. Retrying without changing the request will not help.

401 — we do not know who you are

invalid_credential covers all three on purpose. Distinguishing "revoked" from "never existed" would tell somebody probing that a key had once been real.

402 — the credential is fine, the plan is not

This is the status most people do not expect, and it is the accurate one: you are who you say you are and you are allowed to ask, but the plan does not cover the answer.

quota_exhausted deserves a paragraph

Collection never stops. Past the ceiling your events keep landing — what pauses is your ability to read the period through the API and the dashboard, which close together.

That is the deliberate trade. A gap in the data would be permanent, silent, and impossible to buy back later; a locked screen is none of those things. So nothing is lost while this lasts, and upgrading opens the period you already collected. At your limit covers what to expect.

There is a 10% grace band: the gate turns on past the ceiling, not at 100%, so an ordinary busy month does not read as a failure.

The API closes exactly what the dashboard closes. Past the ceiling the dashboard shows you billing and nothing else — not your analytics, not your site settings, not even the list of which sites you have. The API mirrors that:

The last two are the equivalent of the billing screen staying open. /usage in particular is the answer to a 402 — it tells you how far past the allowance you are. Refusing it on the quota would lock the door and take down the sign explaining why.

403 — we know who you are, and no

site_not_accessible covers "not yours" and "does not exist" with the same message, and a malformed id gets it too. Verified: a real site belonging to another organisation, a well-formed id nobody owns, and not-a-uuid all return identical responses — so the API cannot be used to discover which site ids are real.

404 — no such thing

403 vs 404

A site you cannot see answers 403, never 404 — and so does a site that genuinely does not exist.

That is the point of it. If "not yours" and "no such site" gave different answers, the difference would be a way to ask whether any given id is real, one guess at a time. 404 is used only for resources you already have access to, where a missing one tells nobody anything.

500 — our fault

The detail stays on the server. A stack trace or a database message in a public response is a map of the internals.

Retrying is reasonable, with a delay. If it persists, the status of the underlying store is the first thing we check.

503 — temporarily unable

Distinct from 500 on purpose: this one is expected to clear on its own, so retrying with backoff is the right response rather than an escalation.