Rate limits and versioning

What we throttle, and what we promise not to change without telling you.

The limit

Requests are counted per key, not per company and not per IP, so two integrations at the same customer never spend each other's budget. The current allowance is 120 per minute.

Allowance
120 per minute
Per key. Published from configuration, not from copy.
Scope
/api/v1 only
The limit and its 429 apply to this namespace and nothing else.
On 429
Retry-After
An integer number of seconds. Wait it out; do not tighten the loop.
http · 429
HTTP/1.1 429 Too Many Requests
      Retry-After: 37
      Content-Type: application/json

      { "error": { "code": "rate_limited", "message": "This key has exceeded its rate limit. Wait the number of seconds in the Retry-After header, then retry." } }
Paging is cheaper than polling
A full sweep at limit=200 costs a fifth of the requests of the default 50. If you are polling for changes, subscribe to the webhook instead — that is what it is for, and it does not spend your allowance at all.

Versioning

The version is in the path: /api/v1. There is no version header and no Accept negotiation. If we ever publish a v2, v1 keeps answering.

These are breaking, and get 90 days' notice

  • Removing or renaming a field on an object.
  • Changing a field's type, or the meaning of an existing value.
  • Removing an endpoint, or requiring a parameter that was optional.
  • Renaming or removing an error code, or an event key.
  • Reducing the maximum page size.

These are not breaking, and can land any day

  • Adding a field to an object. Do not validate against an exhaustive key list.
  • Adding an event. Ignore keys you do not recognise.
  • Adding an endpoint, or a new optional parameter.
  • Rewording an error message. The code is the contract; the sentence is for people.
schema_version is not the API version
Every object and every webhook body carries schema_version: 1. It describes the payload shape, and it changes only when that shape changes incompatibly — which is a breaking change and gets the same 90 days. Additive fields do not bump it, so do not treat an unchanged schema_version as a promise that no field was added.

Every change of either kind is written down on the changelog.