A 201 is not a promise: designing for mixed results

Publishing to multiple platforms means partial failure is a normal outcome, not an edge case. How Chirio's per-target statuses, idempotency keys, and first-comment semantics make that safe to build on.

Updated 12d ago

When one API call fans out to several social platforms, "did it work?" stops having a yes/no answer. Instagram can accept the post while Threads rejects the media. X can publish while LinkedIn times out. Any API that hides this behind a single status code is lying to you politely. Chirio's answer is to make partial failure a first-class, boring, well-typed outcome.

Per-target results

POST /api/v1/posts returns 201 Created when the request was accepted and every target attempted — not when everything published. The truth lives in post.targets[]: Each target settles independently with its own status, platformPostId, url, error, and publishedAt. Your integration reads the array, not the HTTP status. That's one loop instead of a special case — and it means a caption that violates one platform's limit doesn't hold the other three hostage.

The rule of thumb

Treat the HTTP status as 'was my request well-formed and attempted', and post.targets[].status as 'what actually happened'. Retry logic, user-facing state, and billing should all key off the targets.

Idempotency, because networks are rude

Publishing can block on platform-side media processing — video on Meta platforms can take minutes. A client that times out and retries would double-post without protection. Chirio accepts an idempotencyKey (or Idempotency-Key header) on publish: a retried request with the same key returns the original post with replayed: true instead of publishing again. The pattern for a safe publish is:

Generate a unique key per logical post — a UUID or your own post id.
Send the publish; on timeout or a 5xx, resend with the same key.
When replayed is true, read back the settled state with GET /api/v1/posts/:id.

First comments fail softly

The link-in-comments pattern — clean caption, URL in a comment posted right after publishing — is common enough that Chirio supports it natively via firstComment on a target. But a comment is subordinate to its post: if the post publishes and the comment fails, failing the whole target would report a failure for content that's live. So comments settle separately too. Each target carries commentStatus, commentId, and commentError alongside the post fields. A failed comment never fails a published post; it's reported where you can see it and act on it.

Why this shape matters

These three decisions — per-target truth, replayable requests, subordinate comments — compose into something bigger: you can build reliable pipelines on top of Chirio without trusting the network, the platforms, or your own retry logic to be perfect. Every state is observable, every retry is safe, and nothing pretends to be atomic that isn't. Tomorrow we'll show what that looks like in production, with a real tenant that wired Chirio into a full editorial pipeline.

Case study: how Aveiro ships social publishing on Chirio

One API for social publishing

Per-target results

POST /api/v1/posts returns 201 Created when the request was accepted and every target attempted — not when everything published. The truth lives in post.targets[]:

{
  "post": {
    "id": "3a1e...",
    "targets": [
      { "platform": "instagram", "status": "published", "url": "https://www.instagram.com/p/..." },
      { "platform": "threads", "status": "failed", "error": "media_processing_failed: ..." }
    ]
  }
}

Each target settles independently with its own status, platformPostId, url, error, and publishedAt. Your integration reads the array, not the HTTP status. That's one loop instead of a special case — and it means a caption that violates one platform's limit doesn't hold the other three hostage.

The rule of thumb

Treat the HTTP status as 'was my request well-formed and attempted', and post.targets[].status as 'what actually happened'. Retry logic, user-facing state, and billing should all key off the targets.

Idempotency, because networks are rude

The pattern for a safe publish is:

Generate a unique key per logical post — a UUID or your own post id.

Send the publish; on timeout or a 5xx, resend with the same key.

When replayed is true, read back the settled state with GET /api/v1/posts/:id.

First comments fail softly

So comments settle separately too. Each target carries commentStatus, commentId, and commentError alongside the post fields. A failed comment never fails a published post; it's reported where you can see it and act on it.

Why this shape matters

Tomorrow we'll show what that looks like in production, with a real tenant that wired Chirio into a full editorial pipeline.