Pinterest API Error ReferenceComplete troubleshooting guide with solutions
Comprehensive reference for Pinterest API errors. Find solutions and troubleshoot common integration issues.
Error Categories
Video
2 errors
Authentication
2 errors
Rate Limit
2 errors
Media
2 errors
All Error Codes
#Video
cover_image_urluser-errorWhen uploading a video to Pinterest, you must also provide a cover image.
Solution:
Pinterest requires a cover image for all video pins. Provide both cover_image_url and cover_image_content_type when uploading videos. The cover image should be JPG or PNG.
cover_image_content_typeuser-errorWhen uploading a video to Pinterest, you must also provide a cover image.
Solution:
Specify the cover image content type (image/jpeg or image/png) along with the cover_image_url. Both fields are required for video uploads.
#Authentication
unauthorizedrefresh-tokenPinterest access token is invalid. Please reconnect your Pinterest account.
Solution:
Your Pinterest access token is no longer valid. This can happen after token expiration or if you revoked app access. Reconnect your account in settings.
invalid tokenrefresh-tokenPinterest access token is invalid. Please reconnect your Pinterest account.
Solution:
Your authentication token is malformed or expired. Go to your account settings and reconnect your Pinterest account to get a new valid token.
#Rate Limit
429retryPinterest rate limit reached. Please try again later.
Solution:
You've exceeded Pinterest's rate limits. Pinterest has daily and hourly rate limits. Wait for the rate limit to reset (typically within an hour) before retrying.
rate limitretryPinterest rate limit reached. Please try again later.
Solution:
Pinterest enforces rate limits to prevent API abuse. Reduce the frequency of your requests and implement exponential backoff in your retry logic.
#Media
invalid mediauser-errorMedia format not supported by Pinterest. Please use JPG, PNG for images or MP4 for videos.
Solution:
Pinterest supports: Images (JPG, PNG), Videos (MP4, MOV). Convert your media to one of these supported formats before uploading.
unsupported formatuser-errorMedia format not supported by Pinterest. Please use JPG, PNG for images or MP4 for videos.
Solution:
Use supported formats - Images: JPG or PNG. Videos: MP4 or MOV with H.264 codec. Ensure your files meet Pinterest's technical specifications.
Best Practices
Error Handling
- →Always provide cover image for video uploads
- →Implement rate limit handling and backoff
- →Validate media format before upload
- →Monitor Pinterest API status
Prevention Tips
- →Include cover_image_url for all videos
- →Use JPG/PNG for images, MP4/MOV for videos
- →Respect rate limits (hourly and daily)
- →Keep tokens fresh and secure
Need Help with Pinterest Integration?
Our API handles error scenarios automatically with smart retry logic and detailed logging.