Cabi.Chat API — Creating cards: idempotency and limits
Creating a card over the Cabi.Chat API is one POST /v0/my/<type>. Two things make it safe to retry and fair to share: an idempotency key on every create and a rate limit per caller. A create retried with the same key returns the first result and never makes a copy.
Idempotency-Key
Networks fail halfway. Without a key, a retry after a timeout may create the same card twice. With a key, it cannot.
- Every create sends
Idempotency-Key: <any unique string>, up to 255 characters; a UUID is the usual choice. That is everyPOST /v0/my/<type>, plus a project's contacts and relations. A create without it answers 400. - Make one key per create attempt and reuse it on every retry of that attempt.
- Same key, same body, first call finished: you get the first answer again, byte for byte, with the header
idempotent-replayed: true. No second card. - Same key, same body, first call still running: 409. Wait and retry.
- Same key, different body: 400. A key belongs to one body.
- A failed create (any non-2xx) frees its key, so the retry may reuse it.
- Personal access tokens and oracle tokens are shown once: repeating that create with the same key answers 409 and never sends the token again. Cabi.Chat API — Personal access tokens
Rate limit
Creates are limited per caller, over all card types together. Above the limit the answer is 429: back off for a few seconds and retry with the same key.
Policies at creation
- To open a new card, send
visibilitytogether withpublicityandpermissionsin onePATCH. Where a card starts and which settings it may take: Cabi.Chat Graph — Card Policies - A card other than a project is anchored to its project with
project, on create or on patch. Cabi.Chat Graph — Data types workspaces: [<nonce>]on create places the card into your workspaces right away.
Handles and text
- Handles and mentions: Cabi.Chat Graph — Handles, mentions and relations
- Text is CommonMark. Posts are Telegram MarkdownV2.
- Two edits of the same article at once: the later one is refused with
card changed concurrently — retry. Read the article again and repeat.
Creating a project with its place, field and contacts, step by step: API pipeline: Create and edit your project page
All endpoints: Cabi.Chat API — Graph endpoints