Envelope and errors

Every successful response wraps its data in the same envelope, and every error returns the same error shape with a machine-readable code and an explicit retry flag. You handle responses once, for every platform and every endpoint.

The success envelope

{
  "platform": "instagram",
  "resource": "profile",
  "capturedAt": "2026-08-06T12:04:11Z",
  "source": "live",
  "data": { "…": "…" },
  "meta": {
    "cursors": { "next": "opaque-cursor" }
  }
}

Shared cores and platform schemas

Openhandle reuses schemas only when their meaning is stable across platforms. For example, every post composes the shared PostCore, PostMetrics, PostAuthor, PostMedia, and MediaReference components. The final response is still an InstagramPost, TikTokPost, or TwitterPost, with a matching platform metrics schema and platform-only relationships.

Check each endpoint schema for field presence and nullability. Measured zeroes remain 0. Instagram profiles, comments, hashtags, and locations omit missing fields. Platform fields remain useful when another platform lacks an equivalent. TikTok can return metrics.downloads, while Twitter can return metrics.quotes, metrics.bookmarks, quoted_post, and reposted_post. Media keeps a preferred url for simple clients, lists mirror addresses of the same file in urls, and exposes every usable public encoding in renditions when the upstream response supplies alternatives.

Each endpoint owns its response schema. Shared names express shared meanings. Every platform uses named groups such as metrics, verification, location, and settings, without an extended wrapper. Each endpoint publishes a fixed key set. A field the provider did not supply is null. Supplied false, zero, empty text, and empty arrays remain as supplied. The answered object promises its identifier, URL, profile handle, post timestamp, and media array; those are never null. The same type reached through another object, such as a post author or a quoted post, is a Reference schema whose identifying fields may be null when the provider left them out. Domain-specific endpoints use dedicated schemas where the provider data is stable enough, for example InstagramStory, InstagramHighlight, TikTokPlaylist, and TikTokEffect. Heterogeneous search endpoints use discriminated search-result nodes, and filter/type endpoints use typed option nodes. No published operation falls back to the generic Entity schema. See the generated OpenAPI document for the exact schema attached to each operation.

The error envelope

{
  "error": {
    "code": "PROFILE_NOT_FOUND",
    "message": "This profile was not found.",
    "requestId": "req_01j8…",
    "retryable": false
  }
}

Always branch on code, not on message. Include requestId when you contact support. When retryable is true, retry with backoff; when it is false, retrying will not help.

Error catalog

Billing and errors

You pay for answers, not attempts. PROFILE_NOT_FOUND, PROFILE_PRIVATE, and other definitive answers are billable: the API did the work and gave you a usable result. Provider failures and internal errors are never charged. PROFILE_BLOCKED is never charged either.