Robust Integrations

A working happy path is not yet a production integration. Networks time out, users retry, collections grow past one page, several actors touch the same document, and something has to notice when they do. This chapter covers the mechanics that make an integration hold up under all of that — each demonstrated with live requests.

The mechanics

• Errors. Every failed request returns one uniform envelope with a machine-readable type and a requestId for support. Branch on the type, log the id.

• Retries. A timeout does not tell you whether the server processed your request. Most create operations accept an Idempotency-Key header, so a retry can never create a duplicate.

• Pagination. Collections return a uniform envelope with offset/limit for shallow access and an opaque cursor for walking large result sets.

• Concurrency. Document reads return the current version as an ETag; writes accept If-Match to refuse overwriting a change someone else made in the meantime.

• Webhooks. Instead of polling, Circularo calls your endpoint when documents change — registered by an organization administrator, and — when you configure a secret — signed so you can trust what arrives.

None of these are mandatory to get started — the API works without them. They become important the day your integration handles real volume, real users, and real documents.

Across the chapter

• One error envelope is the common vocabulary. Every mechanic here reports its failures through it: a 412 from a conditional write, a 422 from an idempotency key reused with a different payload and a 400 from a stale cursor all arrive in the same shape.

• The mechanics are opt-in, and per endpoint. An Idempotency-Key matters on creates, If-Match on document writes, a cursor on the collections that support one. Which endpoint accepts what is documented with that endpoint in the API reference.

• Rate limiting applies to everything. Any endpoint can answer 429 with a Retry-After header, so the retry logic you build for timeouts is worth reusing for that.

• The pages stand on their own. Nothing here builds on the page before it, so reading by need costs you nothing.

Where to start

Read Handle errors first — every other page builds on the error envelope. Then pick by need: Retry requests safely before you add retry logic, Page through collections before you list or search at scale, Guard concurrent writes when several actors may modify the same document, and React to events with webhooks when you would rather be told than keep asking.