Errors, paging and rate limits
Back to the guide
Errors
{ "error": { "code": "...", "message": "...", "request_id": "..." } }
Keep the request_id. It is on every response, successful or not, and it is the
one thing that lets a specific call be traced. Log it.
A 404 means not found or not visible to you. Anything outside your key's reach answers the same way as something that does not exist, so do not treat it as proof that an id is wrong. See Authentication and scopes.
Paging
Lists come back as:
{ "data": [ ... ], "next_cursor": "..." }
Pass cursor to get the next page. limit accepts 1 to 100 and defaults to 25.
Follow next_cursor until it is null. Do not build page numbers out of it — it
is an opaque cursor, not an offset, and constructing one yourself will break.
Rate limits
Every response carries:
RateLimit-Limit
RateLimit-Remaining
RateLimit-Reset
A 429 also carries Retry-After. Wait that long rather than retrying
immediately.
Read the headers as you go rather than waiting to be refused. Backing off when
RateLimit-Remaining gets low is cheaper than handling 429s, and it keeps a bulk job
from starving the interactive application of the same budget.
Writing safely
Reads are cheap; writes are not. A write creates timeline entries and may trigger duplicate checks, so batching reads and spacing writes is the right shape for a bulk job.
Create is not idempotent. Retrying a create that actually succeeded but whose response you did not see will make a second record. If you are retrying creates, check first by the identifying field rather than retrying blindly.