API Basics

Errors

Read the error envelope, decide what to do for each HTTP status, and look up every error code.

Every error has the same shape and a stable code. The code and the HTTP status tell you to fix the request, wait, or reconnect an account.

Error Envelope

Every error response has this body.

{
  "error": "Invalid request: geoRestriction entries must be uppercase ISO 3166-1 alpha-2 codes (e.g. \"US\").",
  "code": "VALIDATION_ERROR",
  "param": "accounts.0.x.geoRestriction.0",
  "requestId": "req_8f2a64c1d3b94e0f9a7c5e2b1d0f3a6c"
}

Prop

Type

Empty fields are left out. A code never changes its meaning. New codes can appear, so handle an unknown one by its HTTP status.

Request Ids

Every response has a Request-Id header, such as req_8f2a64c1d3b94e0f9a7c5e2b1d0f3a6c. Errors repeat it as requestId. Log it so support can find the request.

HTTP Status Codes

StatusMeaningWhat to do
400The request is invalid, or the platform lacks the actionFix the request
401The API key is missing, invalid or deletedSend a valid key. See Authentication
402Billing is blocked, a payment method is needed, or the wallet is shortFix it in the dashboard. See Pricing
403The key is read_only, or this caller cannot take the actionUse a read_write key
404Nothing has this id here, or the id is of another kindCheck the id and its prefix
409A reconnect is needed, the state is wrong, or an Idempotency-Key conflictsRead code, then reconnect or check the state
422The platform refused, such as for a missing permissionFix the cause in code
429A rate limit, or the platform is limiting the accountWait for Retry-After. See Handle 429
500An unexpected errorTry again. If it repeats, contact support
502The platform failed or did not respond, for nowTry again later
503The action is paused, such as uploads or new connectionsTry again later

A 400 or 422 sent again unchanged returns the same error.

Publish Failures

POST /v1/posts checks the whole request first. If any account cannot take the post, nothing is created. After a 201, each post publishes on its own. A post that fails ends as failed, with the reason in error.

{
  "id": "pst_8b7f2c641e3d4f9ab2c56d0e8a4f1b27",
  "groupId": "grp_7d2e5b1a9c4f4a68b3e07f1c2d9a6e45",
  "accountId": "acc_YOUR_INSTAGRAM_ACCOUNT_ID",
  "platform": "instagram",
  "status": "failed",
  "platformPostId": null,
  "url": null,
  "error": {
    "code": "MEDIA_UNFETCHABLE",
    "message": "Could not download media URL (HTTP 403)."
  }
}
  • The posts of one request share a groupId, but each succeeds or fails alone. X can be published while Instagram is failed.
  • A failed post is final. Fix the cause and create a new post.
  • The post.failed webhook carries the same post.
  • PUBLISH_INTERRUPTED means the post may be live. Check the platform before you post again.
  • TOKEN_INVALID from any request marks the account for a reconnect.

More in Failed Posts.

Webhook Failures

An event can arrive more than once, so skip any id you have handled. A failed delivery never affects publishing. Send it again with Retry Delivery. See Delivery and Retries for the full delivery rules.

Billing

Billing errors return 402. A blocked workspace gets PAYMENT_METHOD_REQUIRED or PAYMENT_PAST_DUE on every request, reads included. details.billingState names the cause. An X action the wallet cannot cover returns INSUFFICIENT_WALLET. See Billing Blocks.

Best Practices

  • Build logic on code and the status. Log error, param, details and requestId.
  • Send an Idempotency-Key with every POST, and reuse it on a retry. See Idempotent Requests.
  • Check each post's status. One request can publish on X and fail on Instagram.
  • Reconnect any account that is not active before a publish fails. See Account Status.
  • Retry 429, 500, 502 and 503 after a wait. Fix the request on any other 4xx.
  • Reconnect on TOKEN_INVALID, TOKEN_EXPIRED or CONNECTION_INACTIVE.

Error Codes

Every code, grouped by area.

In the Status column, Post means the code also shows in a post's error.code. Analytics means it shows in an analytics reading's error. Neither is an HTTP error. A code with several statuses lists them all.

Requests and Authentication

CodeStatusCauseFix
VALIDATION_ERROR400, PostA field is missing, unknown or invalid, such as a wrong id kind, a long text, an unsupported option or a bad schedule. As a post error, the platform refused a parameterFix the field in param or error
INVALID_CURSOR400cursor is not a nextCursor of this listUse the last nextCursor, or drop cursor
UNAUTHORIZED401The API key is missing, invalid or deletedSend a valid key. See Create an API Key
FORBIDDEN403A read_only key tried to write, a key limited to some profiles managed profiles or named another profile, or another workspace started the connect sessionUse a read_write key, a key with access to all profiles, or this workspace's key
GROUP_DISABLED403The key's restricted access turned off this part of the API. details.group names itUse a key that has the group
NOT_FOUND404, PostNothing with this id exists in the workspace, or its prefix is wrong. As a post error, the post or its account was removed firstCheck the id
IDEMPOTENCY_KEY_REUSED409The Idempotency-Key was used for another requestUse a new key
IDEMPOTENCY_KEY_IN_USE409A request with this Idempotency-Key is still runningWait for Retry-After, then retry
RATE_LIMITED429, Post, AnalyticsAn API or publishing limit was hit, or the platform slowed the accountWait for Retry-After or the time in the message. See Rate Limits
QUOTA_EXCEEDED429, Post, AnalyticsThe platform is at capacity for this actionTry again after the time in the message
INTERNAL_SERVER_ERROR500An unexpected errorTry again later. If it repeats, contact support with the requestId
SERVICE_UNAVAILABLE503The service is paused for now, such as media uploadsTry again later. If it repeats, contact support with the requestId

Billing and Wallet

CodeStatusCauseFix
PAYMENT_METHOD_REQUIRED402The workspace has 3 or more accounts and no payment methodAdd a payment method in the dashboard
PAYMENT_PAST_DUE402A payment failedUpdate the payment method and pay the invoice
INSUFFICIENT_WALLET402, PostThe wallet cannot pay for an X action. Nothing is created or changed. As a post error, a scheduled X post was not covered at publish timeTop up the wallet, then retry. Check the balance with GET /v1/wallet
USAGE_BILLING_REQUIRED402A 3rd account needs a payment methodAdd a payment method, then connect again
USAGE_BILLING_FAILED402Billing for the new account failed, so it was not connectedCheck the payment method and connect again

Accounts and Connections

CodeStatusCauseFix
ACCOUNT_NOT_FOUND404, AnalyticsNo account has this id in the workspace, or a picked Instagram account has no linked PageUse an id from List Accounts
CONNECTION_INACTIVE409, Post, AnalyticsThe account is disconnected or its access was revokedReconnect the account
CONNECTION_BROKEN409The Instagram account on Facebook Login has no linked PageReconnect the account
TOKEN_INVALID409, Post, AnalyticsThe platform revoked the account's access. The account turns revoked and account.revoked is sentReconnect the account
TOKEN_EXPIRED409, Post, AnalyticsThe platform says the account's access expiredTry again. If it repeats, reconnect
PERMISSION_DENIED422, PostA permission is missing, or the platform refused the actionReconnect and approve every permission. On TikTok, the message may ask for a private account
ACCOUNT_RESTRICTED422, Post, AnalyticsX or TikTok restricted the account, such as a suspension or posting banFix it on the platform, then try again
ACCOUNT_SUSPENDED422, Post, AnalyticsBluesky took down, suspended or deactivated the accountRestore the account on Bluesky
AUTH_FAILED422Bluesky rejected the handle or App PasswordCheck the handle and create a new App Password
CONNECT_FAILED400The account could not be connected, such as when it already isCheck for an existing account
RECONNECT_MISMATCH400A reconnect used another accountReconnect with the same account
BLUESKY_RECONNECT_APP_PASSWORD400A Bluesky reconnect has no identifier and appPasswordSend both
INVALID_REDIRECT_URL400redirectUrl is not HTTPS or has credentials. HTTP works only for localhostSend a valid HTTPS URL
REDIRECT_URL_REQUIRED400The connect session or reconnect needs a redirectUrlSend redirectUrl
INVALID_CONNECT_SESSION400connectSession is malformed, changed or over 10 minutes oldCreate a new connect session
FACEBOOK_PAGES_FAILED400The user's Facebook Pages could not be listedTry again, or create a new connect session
INSTAGRAM_ACCOUNTS_FAILED400The linked Instagram accounts could not be listedTry again, or create a new connect session
PAGE_NOT_FOUND404The user cannot access the picked Facebook PagePick a Page from the candidates
PLATFORM_MAINTENANCE503Connects and reconnects to this platform are pausedTry again later
PROFILE_IN_USE409An API key is limited to the profile you tried to deleteDelete the keys limited to it first
PROFILE_NAME_TAKEN409The name exists in any letter case, or is reservedChoose another name
PROFILE_NOT_FOUND404No profile has the name in the pathList the profiles and use a current name
UNSUPPORTED_PLATFORM400, AnalyticsThe account's platform does not have this actionUse an account on a supported platform
STATS_FAILED502The platform did not return account statsTry again. Reconnect if the message says so
LIST_FAILED502The platform did not return the account's media or postsTry again. Reconnect if the message says so
REVIEWS_FAILED502Facebook did not return the Page reviewsTry again. Reconnect if it keeps failing
PROFILE_FAILED502Facebook did not read or update the Messenger profileCheck the input and try again
CREATOR_INFO_FAILED502, PostTikTok creator info did not load. Creating or editing a TikTok post needs it, so nothing is createdTry again. Reconnect if it keeps failing
BOARDS_FAILED502Pinterest boards could not be listedTry again. Reconnect if it keeps failing
BOARD_CREATE_FAILED502Pinterest did not create the boardCheck the message and try again
SANDBOX_MISMATCHPostThe Pinterest account cannot publish in the current Pinterest environmentDisconnect and reconnect Pinterest

Media

CodeStatusCauseFix
UNSUPPORTED_MEDIA_TYPE400, PostThe file type is not supportedUse a supported format
MEDIA_NOT_FOUND404A media[].id does not exist in this workspaceUse an id from GET /v1/media
MEDIA_NOT_UPLOADEDPostThe file was never uploaded, or the upload expiredUpload the file, then create the post again
MEDIA_TYPE_MISMATCHPostThe uploaded file's type is not its contentTypeCreate a new media item with the right type
MEDIA_TOO_LARGE400, PostThe file is over the size limit for its typeUpload a smaller file
MEDIA_FORMAT_UNSUPPORTED400, PostThe platform does not take the file's format for this kind of post. On a 400, param names the fileConvert the file to a format in the platform's Media Requirements
MEDIA_TOO_LARGE_FOR_PLATFORM400, PostThe file is over the platform's size limit for this kind of post. On a 400, param names the fileCompress the file under the limit in the platform's Media Requirements
MEDIA_UNFETCHABLEPostThe media URL could not be downloadedMeet the Media URL Requirements
INVALID_MEDIAPostThe platform refused the file's format, count, size or kindCheck the platform's media requirements
MEDIA_REQUIREDPostA media post has no mediaAdd media
MEDIA_UPLOAD_FAILEDPostThe platform refused or failed the uploadCheck the media and post again
MEDIA_PROCESSING_FAILEDPostX could not process the mediaRe-encode the file and post again
MEDIA_PROCESSING_TIMEOUTPostThe platform did not process the media in timeUse a smaller or shorter file and post again
CONTAINER_FAILED502, PostInstagram or Threads could not process the mediaCheck the format and size, then post again
URL_OWNERSHIP_UNVERIFIEDPostTikTok refuses media from the URL's domainUpload the file and use its id
REEL_UPLOAD_FAILEDPostFacebook did not accept the reel uploadCreate the post again
STORY_UPLOAD_FAILEDPostFacebook did not accept the story uploadCreate the post again

Publishing

CodeStatusCauseFix
PUBLISH_FAILED502, PostThe platform refused the post without a specific reasonRead error.message, fix the content and post again
PUBLISH_INTERRUPTEDPostThe outcome is unknown, and the post may be liveCheck the platform before posting again
PLATFORM_UNAVAILABLE502, Post, AnalyticsThe platform is down or did not respond. Connecting or reconnecting an account can return it tooTry again later. If it repeats, contact support with the requestId
POST_NOT_PUBLISHED409quotePostId or replyToPostId names a pst_ post that is not liveWait until it is live, or use the platform's post id
TEXT_TOO_LONG400, 422, PostThe text is over the platform or account limitShorten it. See Text Limits
TEXT_REQUIRED400, 422, PostA text post or message has no textAdd text
CAPTION_TOO_LONGPostThe Instagram caption is over 2,200 charactersShorten the caption
INVALID_FIRST_COMMENTPostThe Instagram firstComment is over 2,200 charactersShorten the comment
INVALID_AI_LABELPostInstagram isAiGenerated was sent on a storyRemove it, or post a reel or feed post
UNSUPPORTED_MEDIA_KINDPostThe platform cannot publish this mediaKindUse a mediaKind the platform supports
UNSUPPORTED_FEATUREPostThe platform has no threads, quotes or repliesRemove thread, quotePostId or replyToPostId
INVALID_MULTI_IMAGEPostThe image count is outside the platform's rangeSend a count the platform accepts
DUPLICATE_CONTENT422, PostX rejected the text as a duplicateChange the text
GEO_RESTRICTION_FAILEDPostX rejected the geoRestriction listCheck the country codes, or remove geoRestriction
INVALID_LINKPostThe Bluesky link is not a valid URLFix the link
INVALID_QUOTEPostThe Bluesky post to quote is not a valid at:// URI or was not foundUse an existing post's pst_ id or at:// URI
INVALID_REPLYPostThe Bluesky post to reply to is not a valid at:// URI or was not foundUse an existing post's pst_ id or at:// URI
INVALID_TOPIC_TAGPostThe Threads topicTag is over 50 characters or has . or &Fix the tag
INVALID_AUDIOPostInstagram audioId needs a single video with mediaKind reel or video, on Facebook LoginUse a single video, or reconnect with Facebook Login
INVALID_SPONSORPostAn Instagram sponsor was not found, or a paid partnership was sent without Facebook LoginUse a valid username or id, or reconnect with Facebook Login
INVALID_TRIAL_REELPostAn Instagram trial reel is not a single video, or has sponsorsUse a single video without sponsors
INVALID_CAROUSELPostFacebook carouselCards needs multi_image and one card per imageSend one card per image with multi_image
TEXT_FORMAT_UNSUPPORTEDPostFacebook textFormatPresetId only works on text-only postsRemove it, or post text only
PRIVACY_LEVEL_REQUIREDPostThe TikTok privacyLevel is missing or invalidSend a valid privacyLevel
INVALID_PRIVACY_LEVEL400, PostThe creator does not allow this TikTok privacyLevel. As a post error, their settings changed after schedulingUse a value from GET /v1/accounts/{id}/creator-info
INTERACTION_DISABLED400tiktok.allowComment, allowDuet or allowStitch is true, but the creator turned it off. Nothing is createdSet the option named in error to false. See GET /v1/accounts/{id}/creator-info
SPAM_RISKPostTikTok flagged the post as a spam riskReview the content before posting again
POSTING_LIMIT_REACHEDPostTikTok says the account posted too oftenWait before posting to this account again
CAPACITY_LIMITEDPostTikTok is not accepting more direct posts right nowTry again in a few hours
UPLOAD_LIMIT_EXCEEDEDPostThe YouTube channel reached its upload limitWait until YouTube's limit resets

Edit, Cancel and Delete

CodeStatusCauseFix
NOT_EDITABLE409The post is not scheduled, or was made outside OnepostlyDelete it and create a new post
POST_PUBLISHING409The post is publishing right nowTry again once its status is final
NOT_DELETABLE409Nothing is on the platform. The post failed before it went out, or is a draftNothing to delete. Delete a draft in the dashboard
DELETE_FAILED502The platform did not delete the postTry again later, and check the platform
DELETE_PERMISSION422The account cannot delete this postReconnect and approve every permission, or check the account owns it
THREAD_DELETE_PARTIAL502The first post was deleted, but not all of its threadSend the delete again
MEDIA_DELETE_UNSUPPORTED400Instagram Login accounts cannot delete mediaReconnect with Facebook Login, or use the Instagram app
INVALID_EXTERNAL_ID400, AnalyticsThe Bluesky post id is not an at:// URIUse the at:// URI as platformPostId

Comments and Engagement

CodeStatusCauseFix
NOT_PUBLISHED409, AnalyticsThe post is not published yetWait until it publishes, then call again
ACCOUNT_REQUIRED400A platform post id was sent without accountIdSend accountId too
AMBIGUOUS_TARGET400The post was published to several accountsSend accountId to pick one
POST_ACCOUNT_MISMATCH400A like, bookmark or repost names another account's pst_ postAct as the post's account, or use platformPostId
TARGET_SYNC_FAILED502The platformPostId post did not load from the platformCheck the id and try again
MISSING_EXTERNAL_ID404, AnalyticsThe post or comment has no usable platform idPass a valid id
NOT_A_COMMENT400The id is one of your posts, not a commentUse DELETE /v1/posts/{id}
COMMENT_CREATE_FAILED502The platform did not post the comment or replyTry again
COMMENT_DELETE_FAILED502The platform did not delete the commentTry again
COMMENT_HIDE_FAILED502The platform did not hide or unhide the commentTry again
COMMENT_LIKE_FAILED502Facebook did not like the commentTry again
COMMENT_UNLIKE_FAILED502Facebook did not remove the likeTry again
PRIVATE_REPLY_FAILED502The private reply was not sent. A comment takes one, within 7 daysCheck the comment's age and past replies
COMMENTS_PERMISSION422A comment permission is missing, the comment cannot be deleted, or comments are offReconnect and approve every permission. On YouTube, check comments are on
COMMENTS_UNSUPPORTED400Comments cannot be read for this postNothing to do
UNSUPPORTED_MEDIA400The post is a story, which has no commentsNothing to do
COMMENTS_FAILED502The comments could not be readTry again
INVALID_PARENT400The Bluesky comment to reply to has an invalid idUse a cmt_ id from List Comments
INVALID_COMMENT_ID400The Bluesky comment id is invalidUse a cmt_ id from List Comments
RESOLVE_FAILED404Bluesky could not find the post or comment to reply toCheck that it still exists
ENGAGEMENT_FAILED502The like or bookmark failedTry again. Reconnect if the message says so
ENGAGEMENT_PERMISSION422The account is missing permission for likes or bookmarksReconnect and approve every permission
LIKE_FAILED502The platform did not like the postTry again
UNLIKE_FAILED502The platform did not remove the likeTry again
BOOKMARK_FAILED502The platform did not bookmark the postTry again
UNBOOKMARK_FAILED502The platform did not remove the bookmarkTry again
REPOST_FAILED502The platform did not repost the postTry again
UNREPOST_FAILED502The platform did not remove the repostTry again
REPOST_PERMISSION422The account cannot repostReconnect and approve every permission
UNREPOST_PERMISSION422The account cannot remove the repostReconnect and approve every permission
UNREPOST_REQUIRES_REPOST_ID400The Threads repost was not made through OnepostlyUndo it in the Threads app
REPOSTS_UNSUPPORTED400Reposts cannot be read for this postNothing to do
REPOSTS_UNAUTHORIZED422X rejected the account's access while reading repostsReconnect the account
REPOSTS_FAILED502The reposts could not be readTry again
READ_FAILED502The platform list could not be readTry again
SYNC_FAILED502POST /v1/accounts/{id}/sync could not load the account's postsTry again

Inbox and Automations

CodeStatusCauseFix
CONVO_NOT_FOUND404The conversation does not existCheck the cnv_ id
RECIPIENT_NOT_FOUND404The recipient does not exist. Facebook needs the numeric user idCheck the recipient
RECIPIENT_UNREACHABLE409The recipient does not accept messages from this accountReach them another way
MESSAGE_WINDOW_EXPIRED409The 24-hour Instagram or Facebook messaging window closedWait for the person to message again
CONVO_LOCKED409The Bluesky conversation is lockedNothing to do
INBOX_PERMISSION422The account is missing messaging permissionReconnect and approve every permission
INBOX_FAILED502The platform did not complete the inbox requestTry again. Reconnect if it keeps failing
INVALID_ATTACHMENT400attachmentUrl is not an HTTPS URLUse a public HTTPS URL
ATTACHMENT_UNSUPPORTED400Attachments only work on Instagram and FacebookRemove the attachment
TEMPLATE_UNSUPPORTED400Quick replies, buttons and cards only work on Instagram and FacebookRemove them
INVALID_TEMPLATE400A button lacks url or payload, or an attachment has buttons or cardsFix the buttons
LIMIT_REACHED400The account has the most automations it can haveDelete an automation first
CONFLICT409The automations changed while the request ranSend the request again

Analytics

CodeStatusCauseFix
INVALID_RANGE400since is not before until, or the range is too longFix the dates
TIMELINE_UNSUPPORTED400X posts have no daily timelineUse GET /v1/posts/{id}/analytics
ANALYTICS_PERMISSION422, AnalyticsThe account is missing the insights permissionReconnect and approve every permission
ANALYTICS_FAILED502, AnalyticsThe platform did not return metricsTry again later. Reconnect if the message says so
ANALYTICS_PENDINGAnalyticsThe platform has no metrics yetRead again later
POST_NOT_FOUNDAnalyticsThe post was deleted, or the account cannot see it. The reading is unavailable for goodCheck the post on the platform
VIDEO_ID_PENDINGAnalyticsThe TikTok video is not public yetRead again later
VIDEO_NOT_FOUNDAnalyticsTikTok has no metrics yet, or the YouTube video was removedRead again later, or check the video exists
PRIVACY_RESTRICTEDAnalyticsTikTok only reports metrics for public postsPublish with public_to_everyone

Webhooks

CodeStatusCauseFix
CREATE_FAILED500The webhook endpoint could not be createdTry again. If it repeats, contact support with the requestId
DELIVERY_IN_PROGRESS409The delivery is still being attemptedWait for success or failed, then retry

See Analytics Status for how the analytics codes relate to status.