Threads API errors: codes, causes, and fixes
Threads API errors fall into three groups: authentication tied to Instagram, media processing, and video format. This guide covers the 7 documented codes, how to tell them apart, and the fix that applies to each one. Start by matching the exact code you received, then follow the decision path below before you reconnect an account or re-encode a file.
Authentication errors: revoked, invalid, and invalidated sessions
Threads inherits Instagram's authentication model. Tokens are minted through the Instagram OAuth flow against a linked business account, so most authentication failures look like Instagram failures with simpler shapes. Before doing anything else, separate authentication from media and video problems. If the code is revoked_access_token, token is invalid, or session has been invalidated, reconnecting is the relevant path and re-encoding will not help. If the code is media processing, video format, video codec, or duration exceed, the token is not the problem and reconnecting will not help. That split prevents the two most common wasted fixes: re-encoding a file when the session is dead, and reconnecting an account when the file itself is rejected.
Authentication errors and Instagram-linked token recovery
revoked_access_token means the Threads access token was revoked, typically because the user removed app permission from Instagram's Apps and Websites settings. Because Threads tokens are tied to Instagram, removing permission there breaks Threads access too. The fix is to reconnect through the Instagram-business OAuth flow and confirm the linked Instagram account and the permissions being granted. token is invalid means the token failed validation, which happens when it expired, was revoked, or was signed under a stale Instagram app. The fix is also to reconnect, but first check whether the app configuration changed, since a stale app signature will produce the same failure again after a reconnect. session has been invalidated means the session was forcibly terminated, typically after the user changed their Instagram password or completed a Meta security check. Reconnect to establish a fresh session. In all three cases, verify the linked account in the connect flow so the user knows which Instagram account and permissions are in use, then retry publishing only after the new session is established.
Media processing errors: poll before publishing
media processing means Threads is still processing the uploaded media. Larger video uploads need processing time before the publish step can run, so this is often a timing signal rather than a permanent failure. Poll the container status before publishing instead of retrying the publish call immediately. Treat it as still processing while the status is pending, and only treat it as a failure when the status stops progressing or returns a terminal error. A practical polling checklist is to record the container identifier, poll at increasing intervals, stop when the status reports ready, and re-check the video format, codec, and duration before publishing if processing fails outright. Do not re-upload the same file repeatedly while the original container is still processing, since that creates duplicate containers and makes it harder to tell which one is current.
Video errors: format, codec, and duration
Three video codes cover most upload rejections. video format means the video is not in MP4 with H.264/AAC, because Threads only ingests the same codec set as Instagram. video codec means the video uses an unsupported codec such as HEVC/H.265, and HEVC, AV1, and VP9 are rejected by Threads ingestion. duration exceed means the video exceeds the 5-minute Threads cap, so it must be trimmed or split into a thread. The worked fix for format and codec problems is to re-encode to MP4 with H.264 video and AAC audio, as shown in the code example titled Re-encode video to MP4 with H.264 video and AAC audio. After re-encoding, confirm the output container, video codec, audio codec, and duration before uploading again. If the duration is the only problem, trimming or splitting is faster than re-encoding, but re-encoding after a trim is still needed if the source codec is unsupported.
Quick-reference failure matrix for all 7 errors
Use the table titled Quick-reference failure matrix for all 7 errors to map each code to its category, likely cause, immediate fix, and prevention check. Search the table for the exact code from your response, then apply only the fix in that row. If your code is not in the table, treat it as a different problem rather than forcing it into one of these seven categories.
Pre-publish checklist
Run this checklist before every publish attempt. Confirm the token is valid and the linked Instagram account is the intended one. Confirm the video is MP4 with H.264 video and AAC audio, with no HEVC, AV1, or VP9 streams. Confirm the duration is within the 5-minute cap, or trim and split the content first. Confirm media processing has finished by polling the container status until it reports ready. If any check fails, fix that specific item and re-run the checklist from the top, since a reconnect can change the token state and a re-encode can change the duration or codec state.
| Code | Category | Likely cause | Immediate fix | Prevention check |
|---|---|---|---|---|
| revoked_access_token | Authentication | User removed app permission from Instagram's Apps and Websites settings | Reconnect through the Instagram-business OAuth flow | Confirm the linked Instagram account and granted permissions in the connect flow |
| token is invalid | Authentication | Token expired, revoked, or signed under a stale Instagram app | Reconnect | Check for stale Instagram app configuration before reconnecting |
| session has been invalidated | Authentication | User changed their Instagram password or completed a Meta security check | Reconnect to establish a fresh session | Reconnect promptly after password changes or security checks |
| media processing | Media | Threads is still processing the uploaded media | Poll the container status before publishing | Wait for a ready status instead of retrying publish immediately |
| video format | Video | Video is not in MP4 with H.264/AAC | Re-encode to MP4 with H.264/AAC | Validate container and codecs before upload |
| video codec | Video | Video uses an unsupported codec such as HEVC/H.265 | Re-encode to H.264 | Reject HEVC, AV1, and VP9 before upload |
| duration exceed | Video | Video exceeds the 5-minute Threads cap | Trim or split into a thread | Check duration against the 5-minute cap before upload |
Documented codes from the source page; causes and fixes as documented there.
Frequently asked questions
Why does a Threads authentication error require reconnecting through Instagram?
Reconnect through the Instagram OAuth flow against the linked business account. Threads tokens are tied to Instagram, so removing permission in Instagram's Apps and Websites settings, changing the Instagram password, or completing a Meta security check can break Threads access.
What should I do when I get a media processing error?
Poll the container status before publishing. Larger uploads need processing time, so media processing usually means the upload is still being processed rather than permanently failed. Publish only after the status reports ready.
How do I fix video format, video codec, and duration exceed errors?
Re-encode to MP4 with H.264 video and AAC audio, and keep the video within the 5-minute cap. HEVC/H.265, AV1, and VP9 are rejected, so trim or split longer videos and re-encode unsupported codecs before uploading again.