Skip to main content
Understanding responses, error handling, and status codes for every Partner API endpoint.

​
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": "Workspace 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

CodeMeaningNotes
200SuccessReturned for GET/PATCH requests and POST /posts/retry.
201CreatedReturned only by POST /posts when a post is successfully queued.
400Bad RequestMissing/invalid parameters, unreachable media URLs, etc.
401UnauthorizedAPI key missing, malformed, or revoked.
402Subscription RequiredWorkspace does not have an active plan for Partner API usage.
404Not FoundResource doesn’t exist inside the current workspace context.
422Unprocessable EntityJSON body parsed but failed schema validation (invalid payload).
429Too Many RequestsBack off—respect concurrency guidance (3–10 requests at a time).
500Internal Server ErrorRare; 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.