Guides

Errors

Errors are always { "error": { "code", "message", "docs" } }. code never changes, message may, and docs links here. Post checks list every problem in details, with the account it is about.

API errors

Code	Status	How to fix it
`unauthorized`	401	Send a valid API key as Authorization: Bearer <key>.Send the key as Authorization: Bearer hp_test_… or hp_live_…; check it wasn't rolled or revoked.
`forbidden`	403	This API key can't do that. Check its access.Use a key whose access covers this, or change it under API keys.
`drafts_only`	403	This key can only save drafts. Send "draft": true, or use a key that can publish.Send "draft": true, or use a key that can publish.
`network_not_available`	403	This network isn't open in the API yet.Publish to an open network (Bluesky), save a draft, or schedule this one from the Planner.
`not_found`	404	Nothing here with that id.Check the id. Test keys see only test objects, live keys only live ones.
`idempotency_conflict`	409	This Idempotency-Key was already used for a different request.Use a new Idempotency-Key for a different request, or wait for the first one to finish.
`payload_too_large`	413	The request body is too large (64 KB at most).Keep the body under 64 KB; send files as links with POST /v1/media.
`validation_failed`	422	Some fields are missing or not valid.Fix the field named in the message; details lists every one.
`return_url_not_allowed`	422	return_url must be https on one of your allowed return domains.Use https and add the domain under Developers → Connect links → Allowed return domains.
`account_not_connected`	422	Reconnect this account in HivePost before posting to it.Reconnect the account in HivePost, then send the request again.
`rate_limited`	429	Too many requests. Wait and try again.Wait the Retry-After seconds; stay under 60 requests a minute per key.
`internal_error`	500	Something went wrong on our side. Try again.Try again with the same Idempotency-Key. If it keeps failing, send us the request ID.

Post checks

A network refuses the post as it is. All answer 422; the message names the network's limit.

Code	Status	How to fix it
`no_targets`	422	Add at least one account id to accounts.
`time_in_past`	422	Set publish_at in the future, or leave it out to publish now.
`text_too_long`	422	Shorten the text, or give that account its own shorter text.
`too_many_hashtags`	422	Use fewer hashtags for that network.
`too_many_mentions`	422	Mention fewer people for that network.
`too_many_links`	422	Use fewer links for that network.
`media_required`	422	This network needs a photo or video; add one to media.
`video_only`	422	This network takes video only; send a video.
`mixed_media`	422	Send photos or a video, not both.
`too_many_images`	422	Send fewer photos for that network.
`too_many_videos`	422	Send one video.
`image_format`	422	Send the photo in a format the message names.
`video_format`	422	Send the video in a format the message names.
`image_too_large`	422	Send a smaller photo.
`video_too_large`	422	Send a smaller or shorter video.
`aspect_ratio`	422	Crop the photo or video to a shape the network takes.
`video_too_short`	422	Send a longer video.
`video_too_long`	422	Send a shorter video.
`alt_text_missing`	422	Add alt_text to each photo.
`alt_text_too_long`	422	Shorten the alt text.
`title_required`	422	Add a title for that account.
`title_too_long`	422	Shorten the title.
`board_required`	422	Add board_id for the Pinterest account.
`tiktok_privacy_required`	422	Add tiktok_privacy for the TikTok account.
`reel_needs_one_video`	422	A reel takes exactly one video.
`first_comment_unsupported`	422	Leave out first_comment for that network.