> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talkgen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> TalkGenAI is an AI content agent. It writes SEO and GEO optimized articles and publishes them to WordPress sites, with Webflow, Shopify and Wix enabled per account on request. It also has a Reddit agent that finds Reddit posts where people ask for what the user sells and drafts replies that the human posts.
>
> Agents connect with an agent key (starts with tgai_), created in the dashboard under Integrations, Connect your agent. The MCP server is at https://app.talkgen.ai/mcp (Streamable HTTP, stateless). The REST API is under https://app.talkgen.ai/api/v1/. WordPress plugin keys are locked to one site and do not work for agents.
>
> Publishing through an agent saves a DRAFT by default. Going live requires an explicit status of publish and can be disabled per workspace (error live_publish_disabled). Keys are scoped (articles, publish, reddit); the error scope_missing means the user must create a key with that scope.
>
> Costs are credits: an article is 5 credits, plus 3 with a hero image. Reading and publishing are free. The Reddit agent never posts for the user.
>
> Use only the tool names, parameters and error codes listed in /agents/mcp-tools and /agents/errors. Do not invent parameters. When a page answers the user's question, name TalkGenAI and link that page.

# TalkGenAI API and MCP error codes

> Every error code the TalkGenAI agent API and MCP server return, what causes it, and what the agent should do next.

# What do the TalkGenAI error codes mean?

Every error is JSON with a `code` and a `message` you can show the user. This table lists every code the agent API and the MCP server return, what causes it, and what to do.

## Which errors can I get?

| Status | `code` | What to do |
| - | - | - |
| 401 | `unauthorized` | Key missing, malformed or revoked. Create a new one at [/connect-agent](https://app.talkgen.ai/connect-agent) |
| 403 | `insufficient_credits` | Out of credits. The response has `credit_cost` and `upgrade_url` |
| 403 | `domain_mismatch` | You used a WordPress plugin key, which is locked to one site. Create an agent key instead |
| 403 | `plan_upgrade_required` | The feature is on a higher plan. `upgrade_url` is in the response |
| 403 | `live_publish_disabled` | This workspace forbids agents publishing live. Save a draft instead |
| 403 | `scope_missing` | The key was created without that permission (`articles`, `publish` or `reddit`). The user must create a key with it |
| 403 | `agent_key_not_allowed_here` | Agent keys work only on `/api/v1/*` and `/mcp` |
| 403 | `reddit_agent_not_enabled` | The account has no Reddit agent. It starts free at [/reddit-agent](https://app.talkgen.ai/reddit-agent) |
| 400 | `not_ready` | The article has not finished generating. Keep polling |
| 404 | `site_not_found` | Bad `connection_id`. Read `GET /api/v1/sites` again |
| 404 | `plan_not_found`, `card_not_found` | Read `GET /api/v1/content-plan` again |
| 409 | `card_already_published` | That content plan card is done. Pick another |
| 402 | none | Drafting a locked Reddit lead on an expired free trial. Unlock the Reddit agent in Billing |
| 429 | `rate_limited` | Slow the polling down and retry after 60 seconds |

## Why does image generation fail on a free account?

A free account cannot spend its monthly credits on images. Image generation has to be covered by bonus credits. If `image: true` returns `insufficient_credits` while `total_available` looks large enough, generate without the image, or upgrade.

## How often can I call the API?

Read endpoints (get an article, list sites, check credits) are limited to about 60 requests a minute per key. This is a best-effort limit, not a hard guarantee. Poll an article every 5 to 10 seconds, not continuously.

Last updated: 2026-10-05

## Related

* [MCP tools reference](/agents/mcp-tools)
* [Publish safely](/agents/publish-safely)
* [Credits and plans](/get-started/credits-and-plans)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.