Docs menuErrors

Errors

What a refusal looks like

A refusal is an RFC 9457 problem+json body. Branch on code, never on message; extra fields (hint, issues, reset_at) say how to recover.

application/problem+json
{
  "type": "https://postory.io/docs/api/errors#scope_required",
  "title": "Scope required",
  "status": 403,
  "code": "scope_required",
  "message": "This API key does not have the \"Publish & schedule posts to your connected accounts\" permission. Create a new key with it in Postory under Settings → API keys, and use that key.",
  "required_scope": "postory:publish"
}

Codes by status

Every code

401unauthorized
No key, or the key is wrong, revoked or expired. Send a valid key as Authorization: Bearer.
402credit_limit
Not enough credits for this action. Buy credits in Postory (buy_url), then retry.
403access_paused
AI access is paused for this Postory account. Resume it in AI apps.
403account_blocked
This Postory account cannot publish or edit right now. Contact support.
403app_disconnected
The key or AI app was revoked or disconnected. Create a new key or reconnect the app.
403app_paused
This key or app is paused. Resume it in AI apps.
403email_unverified
The Postory account's email is not verified. Verify it in Postory, then retry.
403forbidden
This key may not act on that object. Check that you use the right account's key.
403insufficient_scope
The key or app no longer has the permission this call needs. Grant it in AI apps or use another key.
403plan_required
The current plan does not include this feature. Upgrade in Postory.
403private_address
Postory will not fetch that URL (a private or local address). Use a public https URL.
403read_only
The Postory account is read-only and cannot import. Subscribe to import again.
403scope_required
The key lacks the permission this call needs (required_scope). Create a key that has it.
403social_account_limit
Your plan's connected-account limit is reached. Buy another account slot or upgrade, then connect it.
403subscription_required
The current plan does not include this. Upgrade in Postory.
404account_gone
The Postory account no longer exists. Stop using this key.
404account_not_found
No connected social account with that id. List accounts for current ids.
404media_folder_not_found
No media-library folder has that id or name. Name one from folders by id or name, or root for files in no folder.
404media_not_found
No media with that id on the post. Read the draft for current media ids.
404not_found
Nothing with that id on this account. Check the id.
404post_not_found
No post or draft with that id on this account. List drafts for a current id.
405method_not_allowed
The route does not take that HTTP method. Use one that the Allow header lists.
409account_choice_required
Several accounts fit and none was named. Ask the user which one and pass its connection_id.
409already_finished
That run has already finished. There is nothing to do.
409already_published
The post is already published. There is nothing to do.
409already_publishing
This post is being published now. Wait, then read its delivery.
409already_running
The same run is already in progress. Wait for it and read its result.
409already_scheduled
This post already has a delivery queued for that account. Reschedule that delivery instead.
409approval_pending
The user has not approved it in the browser yet. Keep the token and call again after their approval.
409browser_approval_required
This account approves every publish in Postory. Send the user to approval_url.
409confirmation_expired
The confirmation token expired. Preview again for a new one.
409confirmation_mismatch
The token was issued for something else. Preview this action again.
409conflict
The post's state does not allow this (for example, it is scheduled). Read it and act on its current state.
409connection_suspended
The social account is paused because the plan's account limit is exceeded. Upgrade or remove an account.
409daily_post_limit
This account has posted as much as it may in 24 hours. Schedule the post at or after next_allowed_at; there is no Retry-After and no override.
409delivery_changed
The delivery changed while it was being moved. Read it again and retry.
409draft_archived
The draft is archived. Restore it from the Archive in Postory (Calendar → List), then schedule it.
409draft_changed
The draft changed after the preview, so nothing was published. Preview it again and show the new preview.
409duplicate_content
The same text was posted on this account too recently. Change the text or schedule it after next_allowed_at.
409idempotency_conflict
That Idempotency-Key was used with a different request. Use a new key for a new request.
409import_active
An import is already running for this account. Wait for it to finish.
409no_account
No social account is connected. Connect one in Postory (connect_url).
409no_x_account
This needs an X account and none is connected. Connect one in Postory.
409partial_delivery
This delivery already has live thread parts. Finish that delivery instead of starting a new one.
409posting_too_often
This account posted less than 10 minutes ago. Schedule the post at or after next_allowed_at; there is no Retry-After and no override.
409quote_changed
The price changed after the preview. Get a new quote and ask the user again.
409reconnect_required
The social account's authorization is no longer valid. Reconnect it in Postory.
409reply_already_answered
That reply already has an answer. There is nothing to do.
409reply_daily_limit
This account has replied as much as it may in 24 hours. Send the replies again at or after next_allowed_at.
409reply_one_at_a_time
A reply post is scheduled on its own, never in a batch. Send it in its own call.
409replying_too_often
This account replied less than a minute ago. Retry at next_allowed_at; there is no Retry-After and no override.
409unsupported_platform
This action is not available on that network. Use an X, Threads or Bluesky account.
410media_expired
The saved media link expired. Upload the file again.
410upload_not_found
No file arrived at the upload URL. PUT the file there first, then attach it.
411length_required
The upload had no size. Send it again with a Content-Length header.
413too_large
The file is too large for the network. Send a smaller file.
413video_size_limit
The video is over your plan's size limit; the message names it. Upload a smaller one.
415not_an_image
That file is not an image. Send an image file.
415unsupported_media_type
That file type is not accepted. Send a supported image or video type.
422bad_cursor
The cursor is unknown or expired. Drop it and list again from the start.
422capability_unsupported
The account's network does not take what the post asks (capability names it: a first comment on LinkedIn). Remove it for that account, or post to an account whose network takes it.
422empty_file
The uploaded file is empty. Upload it again.
422invalid_argument
A value is malformed or out of its window (an id that is not a UUID, scheduled_at outside 2 minutes–30 days). The message names the field.
422media_folder_ambiguous
Two or more media-library folders have that name. Name one by its id from folders.
422not_a_web_url
The value is not an http(s) link. Upload the file instead with POST /api/v1/media.
422parameter_retired
That parameter is no longer accepted. Drop it; the message names what replaced it.
422part_out_of_range
The draft has no part with that number. Read the draft and use an existing part.
422preflight_failed
The post cannot be published or scheduled as it is. Fix what issues lists, then retry.
422profile_private
The X account is protected; only public accounts can be checked by handle. Use a public account.
422unreachable_url
Postory could not download that URL. Check that it is public and answers, or upload the file.
422validation_failed
A field is missing, unknown or the wrong type, or the post breaks a network rule (length, media, thread). Fix what issues lists and send it again.
429media_library_full
The media library has no room for the file (metric: library_files or library_bytes, with current and limit). The user deletes files in Postory (library_url), then retries.
429publishing_limit
Your plan's direct publishes for this billing period are used. Retry after Retry-After, when the new period starts, or upgrade.
429rate_limited
Over a rate limit. Wait the Retry-After seconds, then retry.
429scheduled_posts_limit
Your plan's scheduled posts for this billing period are used. Retry after Retry-After, when the new period starts, or upgrade.
429upload_bytes_daily_limit
Your uploads of the last 24 hours reached your plan's cap. Retry after Retry-After, as the oldest upload ages out, or upgrade.
500internal_error
Something failed on Postory's side. Retry; if it repeats, contact support.
503provider_busy
A data provider is busy or at capacity. Nothing was charged; retry later.
503publish_disabled
Publishing through AI apps and the API is switched off for now. Retry later.
503storage_unavailable
File storage is briefly down. Retry in a minute.
503temporarily_unavailable
A service Postory needs is briefly down. Retry in a minute.
503writes_disabled
Writes through AI apps and the API are switched off for now. Reading still works; retry later.
504timeout
The call took too long. Read the current state before you retry a write.