Error reference
Every error you are likely to hit, with the cause and the fix.
These are the errors agents actually meet. Each row states the cause and the fix, so an agent can usually resolve one without a human.
| Error | Cause | Fix |
|---|---|---|
| plan_upgrade_required | The workspace plan does not include the capability being called — scheduling, recurrence or the media upload handoff on the Free plan. | Read the message out to the person: it names the plan that includes the capability, its price and the upgrade link. Do not retry; the same call is refused until the plan changes. |
| monthly_post_cap_reached | The workspace has used every published post included in its plan this month. | Relay the message, which states the cap, that the allowance resets on the 1st (UTC), and the upgrade link. Retrying is refused until then. |
| key_monthly_cap_reached | The agent key itself has a monthly publish cap set by the site owner and has reached it. | Ask the owner to raise or clear the cap on that key in Agents & Keys, or use a different key. |
| media_not_found | featured_image_id points at an attachment that does not exist on that site, or a media_ref that was never produced. | Call list_media and use an id from the result, or run the upload handoff again. |
| media_not_an_image | The uploaded or referenced file is not one of the accepted image types once its bytes are inspected. | Upload a real JPEG, PNG, GIF, WebP or AVIF. Renaming a file does not change what it is. |
| ambiguous image input | More than one of featured_image_url, featured_image_id and featured_media_ref was supplied. | Send exactly one. Pressbotics rejects the call rather than guessing which you meant. |
| upload expired | get_media_upload returns status "expired": the 60-minute window elapsed, or the file was never uploaded. | Call create_media_upload again and give the person the new link. |
| wp_auth_failed | WordPress did not authenticate the stored credential at all — usually a revoked Application Password, or an email address used where the username was required. | Reconnect the site in the dashboard and create a fresh Application Password. This is the only error that means reconnect. |
| wp_permission_denied | WordPress found the post and authenticated the credential, but the connected user is not allowed to edit that post. A WordPress role or ownership problem. | Give the connected WordPress user a role that can edit the post (Editor or above), or connect as a user who can. Do NOT reconnect the site — the credential is working. |
| wp_not_found | The target does not exist on the site: an update_post post_id that was deleted or never existed, or a REST route the site does not serve. | Confirm the post id with list_content. If the REST API is disabled, re-enable it. |
| wp_schedule_unverified | WordPress did not hold the post as "future" at the exact requested instant, so the schedule was not trusted. The post was reverted to draft. | Check the site's own clock and timezone, then schedule again. Nothing is left scheduled — the post is a draft on the site. |
| wp_publish_unverified | WordPress did not report the post as "publish" after an immediate publish, so publication was not trusted. The post was reverted to draft. | Run site_health, then publish again. The content is safe as a WordPress draft. |
| ambiguous_publish_at | publish_at carried no timezone information, so the intended instant is unknowable. | Send an ISO 8601 timestamp with an offset (2026-09-20T15:30:00-04:00), or a naive time plus an explicit IANA timezone. Nothing is guessed. |
| nonexistent_local_time | The local time requested does not exist — it falls in the hour a clock-forward DST change skips. | Pick a time outside the gap, or send an explicit UTC offset so the instant is unambiguous. |
| ambiguous_local_time | The local time requested happens twice — it falls in the hour a clock-back DST change repeats. | Send an explicit UTC offset to say which of the two you meant. |
| invalid_calendar_date | The date does not exist: 31 November, 30 February, or a non-leap 29 February. | Send a real calendar date. |
| invalid_utc_offset | The offset in the timestamp is not a real UTC offset. | Use an offset between -14:00 and +14:00, or an IANA timezone name. |
| site_timeout | WordPress accepted the request but did not answer in time. Common on shared hosting with large image sideloads. | Retry with the same idempotency_key. Use a smaller image if it recurs. |
| site_unreachable | The site could not be contacted at all: DNS failure, TLS failure, firewall, or an address that is not publicly routable. | Check the site is up over HTTPS from the public internet, then run site_health. |
| seo_status: unsupported | SEO fields were requested on a site without both the companion plugin and an SEO plugin (Yoast, verified; Rank Math, supported but untested). | Install both, then run site_health. The post itself still published. |
Errors versus partial success
Most of the list above stops the action. The per-component statuses are different: image_status "failed" or taxonomy_status "partial" mean the post published and something attached to it did not. Do not report those as failures, and do not republish — fix the component with update_post.
Retrying safely
site_timeout is the one worth retrying: WordPress may have accepted the post before the connection gave up. Retry with the same idempotency_key and you get the original action back rather than a duplicate. Without a key, a retry is a second post.
When the error is not in this list
- Run site_health — most unexplained failures are the site being unreachable or a credential that stopped working.
- Check the action in Activity. Every action records its outcome, including the underlying message.
- Read post_url and render_check before deciding something failed. A reverted post did publish, then failed to render.