Response Pattern

Consistent JSON response envelope and error handling for the Genviral social media posting API. Every endpoint - TikTok, Instagram, YouTube, Pinterest, LinkedIn, Facebook - returns the same typed structure for easy parsing by AI agents and automation scripts.

Understanding responses, error handling, and status codes for every Partner API endpoint. Designed for easy parsing by OpenClaw agents, Claude Code, and any programmatic integration.

Envelope Structure

All endpoints return the same typed envelope so you can branch on ok once and stay type-safe everywhere else.

ok · boolean · required

Indicates success (true) or failure (false).

code · number · required

Mirrors the HTTP status code returned by the endpoint.

message · string · required

Human-readable context for logs or UI surfaces.

data · object

Present only when ok is true. Contains the payload documented for each endpoint.

error_code · string

Optional machine-friendly identifier for failures (e.g., invalid_token, subscription_required).

{
  "ok": true,
  "code": 200,
  "message": "Accounts retrieved",
  "data": { "...": "..." }
}

{
  "ok": false,
  "code": 401,
  "message": "API key not found",
  "error_code": "invalid_token"
}

When ok is true, data is guaranteed to exist. When ok is false, data is omitted, so you can rely on that distinction for strict typing in TypeScript, Swift, or Go clients.

Sample Handling

const res = await fetch("https://www.genviral.io/api/partner/v1/accounts", {
  headers: { Authorization: `Bearer ${process.env.GENVIRAL_TOKEN}` },
});
const payload = await res.json();

if (!payload.ok) {
  throw new Error(`Genviral error ${payload.code} – ${payload.message}`);
}

payload.data.accounts.forEach((account: any) => {
  console.log(account.id, account.type, account.platform);
});

response = requests.get(
    "https://www.genviral.io/api/partner/v1/posts",
    headers={"Authorization": f"Bearer {GENVIRAL_TOKEN}"}
)
data = response.json()

if data["ok"]:
    print(data["data"]["summary"])
else:
    raise RuntimeError(f"Genviral error {data['code']}: {data['message']}")

Common Status Codes

Code	Meaning	Notes
200	Success	Returned for GET/PATCH requests, POST /posts/retry, and idempotent POST /posts replays that return an existing post instead of creating a new one.
201	Created	Returned by fresh create-style requests such as POST /posts, POST /slideshows/generate, POST /packs, POST /packs/:pack_id/images, POST /templates, POST /templates/from-slideshow/:slideshow_id, and POST /slideshows/:slideshow_id/duplicate.
202	Accepted	Returned for async-start endpoints such as POST /studio/videos/generate.
400	Bad Request	Missing/invalid parameters, unreachable media URLs, etc.
401	Unauthorized	API key missing, malformed, or revoked.
402	Subscription Required	Active Creator, Professional, or Business subscription is required.
403	Forbidden	Tier or scope denied (e.g., tier_not_allowed for Scheduler).
404	Not Found	Resource doesn’t exist in the authenticated key scope.
422	Unprocessable Entity	JSON body parsed but failed schema validation (invalid payload).
429	Too Many Requests	Back off-respect concurrency guidance (3–10 requests at a time).
500	Internal Server Error	Rare; retry with exponential backoff and contact support if needed.

error_code is the fastest way to branch on known issues (e.g., invalid_media_url, post_not_mutable). Log both code and error_code for observability.

Handling 422 invalid_payload

When payload validation fails at the schema/shape layer, Partner API returns 422 with schema-level and field-level details. Account-aware rules that require resolved account metadata (for example a caption that is valid for Facebook but too long for a selected Pinterest account) surface later as 400 validation_failed. Unsupported platform-specific objects such as facebook, instagram, linkedin, and youtube are rejected here because Partner API currently supports only tiktok and pinterest settings objects.

{
  "ok": false,
  "code": 422,
  "message": "Invalid payload",
  "error_code": "invalid_payload",
  "issues": {
    "formErrors": ["Unrecognized key(s) in object: 'facebook'"],
    "fieldErrors": {
      "caption": ["String must contain at most 63206 character(s)"],
      "accounts": ["Expected object, received string"]
    }
  }
}

Recommended handling:

1. Detect code === 422 and error_code === "invalid_payload".
2. Read both issues.formErrors and issues.fieldErrors.
3. Fix field shape/data and retry.
4. Do not retry unchanged payloads.

if (!payload.ok && payload.code === 422 && payload.error_code === "invalid_payload") {
  const formErrors = payload.issues?.formErrors ?? [];
  const fieldErrors = payload.issues?.fieldErrors ?? {};
  console.error("Invalid payload", { formErrors, fieldErrors });
  throw new Error("Fix payload shape before retrying");
}