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
- →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 Pinterest API
- →Compress images and optimize media before upload
- →Implement rate limiting in your application
- →Monitor Pinterest Platform Status regularly
Need Help with Pinterest Integration?
Our API handles cover image requirements and media validation automatically.