Where: your AI tool shows these messages. Your usage is under Home → Connect your AI tools → Your tools.
Plan allowances#
The workspace owner's plan applies, counted across all the owner's workspaces.
| Owner's plan | Lifetime, older plans and the free trial | Growth | Pro | Agency |
|---|---|---|---|---|
| AI-tool connections | 3 | 3 | 10 | Unlimited |
| AI actions a month, shared with Hero_Agent | 30 | 2,000 | 10,000 | Unlimited (fair use) |
| Read the Social Inbox | No | Yes | Yes | Yes |
| Reply in the Social Inbox | No | No | Yes | Yes |
- 1 action = one post created, or one inbox reply sent. Everything else is free. See What it costs.
- Actions reset at the start of each calendar month (UTC). Unused actions don't carry over.
- Connected AI tools don't use Hero_Agent chat messages.
- Each tool in each workspace is one connection, whether or not it has been used yet.
- The Agent Growth, Agent Pro and Agent Agency add-ons give the same as Growth, Pro and Agency.
All plan details: AI plans and your monthly AI allowance.
When the month's actions run out#
- Creating a post or sending a reply fails. Your AI tool gets "An unexpected error occurred while processing your request.".
- Nothing is charged and nothing is created.
- Everything free keeps working: reading, reports, editing, scheduling, publishing, uploading media and Hero_Photo images (which use photo credits).
- What to do: check Actions this month under Your tools. Wait for the 1st of next month (UTC), or move to a bigger AI plan in Billing.
In Hero_Agent's chat on Home, the same limit shows as "You've reached your action limit ({used}/{limit})."
Rate limits#
| Limit | Value | How it's counted | What your AI tool gets |
|---|---|---|---|
| Calls per minute | 300 | Per connection, over any rolling minute. Every request Heropost handles for the tool counts, reads included, so one tool call can count several times: saving one post is about 10, a full 25-post create_posts about 275. |
"Rate limit reached for this agent connection (300 calls per minute). Wait a moment and retry." |
| Requests at the same time | 16 | Per connection | "Too many requests in flight for this account. Retry in a moment." (HTTP 429) |
| Failed sign-ins | 10 a minute | Wrong or broken links from the same network address | "Too many failed authentication attempts. Wait a minute and try again with a valid agent key." (HTTP 429) |
If you hit them: wait a minute and ask again. For many posts, ask for one batch: create_posts saves 25 and schedule_posts schedules 50 in one call. If your AI tool keeps calling in a loop, stop it and start a new chat. Developers: send fewer requests in parallel and retry after a short pause.
Sizes per call#
| Tool | Limit |
|---|---|
create_posts |
25 posts |
schedule_posts |
50 posts |
update_workspace_knowledge |
40 facts |
list_social_accounts |
300 accounts (200 by default) |
list_posts |
50 posts (20 by default) |
get_posts_by_date_range |
62 days; 100 posts per call; 12 in full, more as an overview |
list_media |
50 items (30 by default); search looks at your newest 200 |
list_inbox_threads |
100 threads (20 by default) |
get_top_posts |
20 posts (5 by default) |
generate_image |
One image, up to 2 photo credits; up to 6 subjects |
| Any request | 1,000,000 bytes |
Text and field limits#
| Field | Limit |
|---|---|
| Post title | 50 characters; longer titles are shortened |
| Brand voice | 4,000 characters |
| A business fact | 4,000 characters |
| Brand kit | 20 colors, 10 fonts, 10 logos; labels up to 50 characters; font names up to 100 |
| Hero_Photo subject | Name up to 100 characters, description up to 2,000, up to 20 photos |
| Hero_Photo prompt | 3 to 2,000 characters |
| Scheduled date | More than 10 seconds ahead; seconds are dropped |
| Captions and media | Each network's own rules, checked as in the post editor. See Character limits and media specs. |
Waiting times#
- Each request: if Heropost takes more than 30 seconds to answer, the tool gets "Heropost API request timed out. Retry in a moment." Check what happened (for example with
list_posts) before trying a write again, so you don't save a post twice. publish_postanswers straight away; publishing finishes in the background.get_post_statusgives the result on each account.generate_imagewaits about 100 seconds. If the image isn't ready, it answersGENERATING; the image lands in the Media Library within a minute or two.
Link expiry#
A link expires after 180 days without use. Every use restarts the 180 days, so a link in regular use doesn't expire. An expired link gets "This link expired because it had not been used for 180 days. …". Press New link under Your tools and update your AI tool.
Error messages#
Heropost's messages are written for your AI tool, and often say what to call next. Most of the time the tool fixes its request by itself. Some tools show > instead of → in these messages.
When the tool connects#
These come back before any tool runs, as JSON: {"error": "…"}.
| Status | Message | What it means | What to do |
|---|---|---|---|
| 401 | "An agent key is required (Authorization: Bearer hp_ag_...)." | No key arrived, or the link was cut short. | Paste the whole link again, or press New link. |
| 401 | "That is not a Heropost link. Check it in Heropost under Home → Connect your AI tools → Your tools, or connect the tool again." | The key isn't one Heropost knows: the link was changed or is incomplete. | Press New link under Your tools and paste the whole new link. |
| 401 | "This link expired because it had not been used for 180 days. Make a new one in Heropost: Home → Connect your AI tools → Your tools." | Not used for 180 days. | Press New link and update the tool. |
| 401 | "This link was removed. Connect the tool again in Heropost: Home → Connect your AI tools." | The tool was removed, or its link was replaced with New link. | Use the newest link, or connect the tool again. |
| 429 | "Too many failed authentication attempts. Wait a minute and try again with a valid agent key." | 10 or more wrong links from your network in a minute. | Wait a minute, then fix the link. |
Developers sending the key in a header may also see "Missing agent key. Send your Heropost agent key in the 'Authorization: Bearer hp_ag_...' header." or "Invalid agent key format. Keys look like 'hp_ag_' followed by 43 characters. …". Send the whole key: hp_ag_ and 43 more characters.
Permissions and plan#
| Message | What it means | What to do |
|---|---|---|
| "This agent key is draft-only — it can't publish or schedule posts. Create the post as a draft for the owner to review, or ask the workspace owner to enable publishing in Heropost under Home > Connect your AI tools." | Publish and schedule is off for this tool. | Switch it on under Your tools → Permissions, or schedule the draft yourself. |
| "This agent key is draft-only — it can't modify a post that has already been scheduled, published, or submitted for approval. …" | Same switch, for posts that aren't drafts. | Same. |
| "One or more accounts are outside this agent key's account scope. Use list_social_accounts to see the accounts this key can work with." or "Account id(s) {ids} are outside this agent key's account scope. …" | Which accounts doesn't include that account. | Add it under Your tools → Permissions → Which accounts, or use another account. |
| "This agent key is scoped to another workspace." | The tool used something from another workspace. | Use this workspace's accounts and posts, or connect the tool in the other workspace. |
| "This workspace requires human approval before posts can be scheduled or published. …" | Approvals are on for the workspace. | The tool sends the post for approval; approve it in Team → My Approvals. |
| "Post {id} is pending approval. It must be approved or rejected in Team > Approvals before it can be scheduled or published." | The post is waiting for review. | Approve or reject it first. |
| "This agent key doesn't have inbox access. …" | Read the inbox is off. | Switch it on under Your tools → Permissions. |
| "Agent inbox access requires an agent add-on plan (Agent Growth or higher). …" | The owner's plan doesn't let AI tools read the inbox. | Move to Growth or higher in Billing. |
| "This agent key can't reply or react in the inbox. …" | Reply in the inbox is off. | Switch it on under Your tools → Permissions. |
| "Agent inbox replies require the Agent Pro or Agent Agency add-on. …" | The owner's plan doesn't let AI tools reply. | Move to Pro or Agency in Billing, then switch on Reply in the inbox. |
| "Analytics on this workspace's plan cover the last {N} days. Ask again with from = {date} or later (a plain date, UTC). …" | Your plan's analytics don't go back that far. | Ask about a shorter period, or upgrade for longer history. |
| "This needs {N} photo credits — you have {M}." | Not enough Hero_Photo credits. | Add credits or wait for your monthly credits. See Hero_Photo credits. |
Rate limits and temporary problems#
| Message | What it means | What to do |
|---|---|---|
| "Rate limit reached for this agent connection (300 calls per minute). Wait a moment and retry." | Over 300 calls in a minute, often a tool stuck in a loop. | Wait, then ask again. Use batch tools for many posts. |
| "Too many requests in flight for this account. Retry in a moment." | More than 16 calls at the same moment. | Try again in a moment. |
| "Heropost API is unreachable right now. Retry in a moment." or "Heropost API request timed out. Retry in a moment." | Heropost couldn't answer in time. | Try again in a moment. Check before repeating a write. |
| "Heropost API returned an unexpected response (HTTP {code})." "Heropost API request failed (HTTP {code})." "Heropost API returned no data." "Heropost API returned an error." | A temporary problem. | Try again. If it keeps happening, contact support. |
Checks on what the tool sent#
| Message | What it means | What to do |
|---|---|---|
| A sentence about a parameter, such as "limit must be between 1 and 300." or "Max 25 posts per create_posts call — split the batch." | A value is outside the tool's rules. | The AI tool fixes it and tries again. Every tool's messages: Tool reference. |
| "scheduledDate {date} is not in the future (it is now {time}Z, UTC). Pick a later time, or leave scheduledDate out to save the draft without one." | The time has passed, or is less than 10 seconds away. | Ask for a later time, or save the draft without one. |
| "Validation failed: {details}" | Heropost's checks refused a value; the details say which. | Ask the tool to fix what the details say. |
| "Unable to post because {network} requires …" and the other network messages | The post breaks a network's rules, the same as in the post editor. | Fix what the message says, then schedule again. Every message: Every error message, explained. |
| "Post {id} cannot be published because it is in the process of publishing or has already been published." | It's already going out. | Check it with get_post_status. |
| "Post {id} cannot be published because it has no active selected social networks to publish." or "… one or more of the selected social networks do not have active accounts." | No account on the post can publish: none is selected, or one needs reconnecting. | Reconnect the account, or change the post's accounts. See Reconnect an account. |
When Heropost refuses several things at once, the messages come back together, separated by a vertical bar.
"An unexpected error occurred while processing your request."#
Heropost doesn't pass on the details of some errors, including some of its checks on what the tool sent. Your AI tool then shows only this sentence. The most common reason is that the month's AI actions are used up: it then happens when the tool tries to create a post or send a reply.
- Check Actions this month under Home → Connect your AI tools → Your tools.
- If it's at the limit, wait for the 1st of next month (UTC) or move to a bigger AI plan in Billing.
- If it isn't, ask the tool to try again. If it keeps happening, contact support with the time, the AI tool, and what you asked.
Questions#
Do reading and reports count toward the rate limit?
Yes. They're free, but every request counts toward the 300 calls a minute. Normal use doesn't come close; loops and very large jobs do.
Can I buy more actions without changing plan?
No. To get more actions, move to a bigger AI plan in Billing.
Why did my AI tool stop halfway through a big batch?
Usually the month's actions ran out (it then gets "An unexpected error occurred while processing your request.") or it hit the rate limit. Posts saved before that are in Content → Drafts. Check Actions this month, then ask it to carry on from where it stopped.
Does a link expire if I use it every day?
No. Every use restarts the 180 days.