Errors, pagination & rate limits

Status codes, paging through results, and staying within limits.

Status codes

Code	Meaning	What to do
200	Success	—
201	Created	—
400	Bad request	Fix the request body or parameters.
401	Unauthorised	Missing, malformed or revoked token.
403	Forbidden	Valid token, insufficient scope.
404	Not found	Wrong ID, or a resource in another account.
422	Validation failed	Read the response body for the specific field.
429	Rate limited	Back off and retry.
5xx	Server error	Retry with backoff.

Telling 401 from 403

401 means the token was not accepted — missing, malformed, or revoked.

403 means the token is fine but lacks the scope. If you get this on a write, your key is probably read-only. See API keys.

Error bodies

Errors return JSON describing what went wrong. Log the whole body when debugging — the message names the specific field on validation failures, which saves guessing.

Pagination

List endpoints are paginated. Page through using the parameters the endpoint documents rather than requesting a very large page.

Never assume you have everything from the first response. A list that looks complete in testing will silently truncate in production when the account has more data.

Rate limits

Requests are rate limited per account. Exceeding the limit returns 429.

Handle it properly:

• Back off exponentially. Wait, then double the wait on each subsequent failure.
• Add jitter. Randomise the delay so parallel workers do not retry in lockstep.
• Respect any retry-after header if one is returned.
• Cap retries. Give up eventually and surface the failure.

Retrying immediately in a tight loop makes things worse and can extend the limit.

Avoiding limits

Use webhooks instead of polling. This is the main one. Polling every minute for new calls burns your limit and gives you stale data; a webhook delivers it immediately and costs one request. See Webhook events.

Batch where an endpoint supports it.

Cache what does not change. Team members and numbers do not need refetching every request.

Filter server-side. Request what you need rather than fetching everything and filtering locally.

Retrying safely

Retry 429 and 5xx. Do not retry 4xx other than 429 — the request is wrong and will stay wrong.

For writes, make retries safe. A POST that times out may have succeeded; retrying blindly creates a duplicate. Where possible, check before retrying.

Timeouts

Set a sensible client timeout and treat a timeout as an unknown outcome rather than a failure. The request may have been processed.