Threads API Error ReferenceComplete troubleshooting guide with solutions
Comprehensive reference for Threads API errors. Find solutions and troubleshoot common integration issues.
Error Categories
Authentication
3 errors
Media
1 error
Video
3 errors
All Error Codes
#Authentication
revoked_access_tokenrefresh-tokenThreads access token is invalid or revoked. Please reconnect your Threads account.
Solution:
Your Threads access token was revoked. This happens when you remove app permissions or Instagram security detects suspicious activity. Reconnect your account.
token is invalidrefresh-tokenThreads access token is invalid or revoked. Please reconnect your Threads account.
Solution:
Your token is no longer valid. Threads tokens are tied to Instagram accounts. Reconnect your Threads account through Instagram business account.
session has been invalidatedrefresh-tokenYour Threads session has expired. Please reconnect your Threads account.
Solution:
Your Threads session expired. This can happen after password changes or security checks. Reconnect your Threads account to establish a new session.
#Media
media processingretryThreads is still processing your media. Retrying...
Solution:
Threads is still processing your uploaded media. This is normal and the system will automatically retry. Large videos may take longer to process.
#Video
video formatuser-errorVideo format not supported. Please ensure video is H.264/AAC MP4 format.
Solution:
Threads requires MP4 videos with H.264 codec and AAC audio. Convert your video to this format using tools like FFmpeg or HandBrake.
video codecuser-errorVideo format not supported. Please ensure video is H.264/AAC MP4 format.
Solution:
Video codec not supported. Use H.264 (video) and AAC (audio) codecs. Avoid using HEVC/H.265 or other modern codecs that Threads doesn't support yet.
duration exceeduser-errorVideo duration exceeds Threads' limit (5 minutes max).
Solution:
Threads videos must be 5 minutes or less. Trim your video to fit within this limit. Consider splitting longer content into multiple posts.
Best Practices
Error Handling
- →Implement automatic retries for rate limit and service errors
- →Store refresh tokens securely and handle token refresh flows
- →Log all errors with context for debugging
- →Show user-friendly error messages in your UI
Prevention Tips
- →Validate content before sending to Threads API
- →Compress videos and optimize media before upload
- →Implement rate limiting in your application
- →Follow Instagram Community Guidelines and Terms of Service
Need Help with Threads Integration?
Our API handles media processing, format validation, and automatic retries.