Response Pattern - Genviral

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.

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, or a text-only post sent to TikTok) surface later as 400 validation_failed. Unknown provider keys under settings are rejected here because Partner API fails closed on unrecognized platform settings.

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

Recommended handling:

Detect code === 422 and error_code === "invalid_payload".
Read both issues.formErrors and issues.fieldErrors.
Fix field shape/data and retry.
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');
}

​Envelope Structure

​Sample Handling

​Common Status Codes

​Handling 422 invalid_payload

Envelope Structure

Sample Handling

Common Status Codes

Handling `422 invalid_payload`