When you evaluate an API, the demo sells the payload: the post, the transcript, the profile. In production, what you touch every week is the envelope—meta (identity, credits, versioning) and typed errors that mirror the happy path—not the shape of a single caption field.

The quiet contract

Raw platform JSON mirrors whatever the network returned last Tuesday. A good API does not turn your app into an archaeologist. A quiet contract is boring on purpose: same top-level shape for success and failure, one place for requestId and what it cost, errors you can branch on without scraping HTML. That is the gap between “we integrated TikTok” and “we can run this for a year.”

What a good envelope carries

A production-grade envelope answers a few questions without a support thread: which request (correlate logs and tickets), what it cost on metered routes, what broke (codes and retry hints), and room to version without breaking every client.

For Social Fetch, successful bodies pair data with meta: requestId, creditsCharged on metered routes, and version. Errors follow the same mental model so your handler stays one code path. GET /v1/whoami still validates your key without charging credits when you only need a smoke test.

A real metered call looks like this (same x-api-key header as Quickstart). Example: GET https://api.socialfetch.dev/v1/tiktok/profiles/charlidamelio. The data object below is heavily trimmed—the full profile has more fields; meta is the part you log and paste into support:

{
  "data": {
    "lookupStatus": "found",
    "profile": {
      "platform": "tiktok",
      "handle": "charlidamelio",
      "displayName": "charli d'amelio",
      "verified": true,
      "profileUrl": "https://www.tiktok.com/@charlidamelio"
    },
    "metrics": {
      "followers": 157118150,
      "following": 1370,
      "likes": 12065883466,
      "posts": 3056
    }
  },
  "meta": {
    "requestId": "req_07d1da65-c0ca-4482-820a-15f1b266eede_pg_1170a59e",
    "creditsCharged": 1,
    "version": "v1"
  }
}

Debuggability is a product feature

The envelope turns “something broke” into a bounded incident: one requestId to log and paste, instead of a user story. The habit is small—log meta.requestId on failure, surface it when you re-wrap errors—and it is how you sleep.

Why this matters more for social data

Upstream platforms change layouts, limits, and edge cases without your roadmap. You will fail in ways that are not your fault. When that happens you still need honest domain data when the fetch works and honest operational data when it does not. The envelope is where that second part lives.

Where to go next

Use Quickstart for auth and headers, keep Errors nearby once you leave the happy path, and check Pricing when you estimate volume.

Boring envelope, interesting product.