Pinterest API errors
Pinterest API errors during pin creation usually fall into four groups: authentication, rate limit, media format, and video cover requirements. This guide covers the eight documented Pinterest API v5 codes, explains how to distinguish them from the status code and the fields present in your request, and gives a concrete fix for each one.
Pinterest API errors: 8 documented errors at a glance
Pinterest API v5 is comparatively straightforward for pin creation, but a small set of recurring failures accounts for most debugging time. The most common are a rejected or expired access token, a rate limit response, a media file outside the supported formats, and a video pin submitted without its required cover image. Start by matching the returned code to its category, then check the specific cause listed for that code before changing unrelated parts of the request.
Failure matrix: code, category, cause, and fix
Use the status code first, then the error code, then the request fields. A 401 response points to authentication, so check token age, token format, and whether the user revoked access before touching media. A 429 response points to throttling, so check burst size and timing rather than credentials or file format. A media error with a successful authentication and no throttling points to the file itself, so check extension and codec. A video error points to the cover fields, so check whether cover_image_url is present and whether cover_image_content_type declares a supported MIME type that matches the actual file. This order prevents the common mistake of converting a file when the real problem is an expired token, or reconnecting an account when the real problem is a missing cover image.
Authentication errors: unauthorized and invalid token
The unauthorized code is returned with HTTP 401 when Pinterest rejects the access token. The usual cause is token expiry, since Pinterest tokens last 30 days, or the user revoking app access. The fix is to reconnect the account and retry with a fresh token. The invalid token code is also returned with HTTP 401, but the cause is different: the token format is wrong, or the token was minted under a Pinterest app that has since been deleted. Reconnecting is again the fix, but check the token format and the app it was minted under first so the same invalid token is not reused.
Rate limit errors: 429 and throttling
The 429 code means the Pinterest rate limit has been reached. Pinterest enforces per-app and per-user request caps that reset hourly, so the practical fix is to wait for the reset window or implement exponential backoff with jitter. The rate limit code describes throttling reached through a different code path, with the same underlying cause. For both, reduce burst size, space out retries, and avoid tight retry loops that keep the limit saturated.
Media format errors: invalid media and unsupported format
The invalid media code means the media file is not in a supported format. Pinterest accepts JPG and PNG for images and MP4 and MOV using H.264 for video. The unsupported format code means the file extension or codec is not on the allowlist, which commonly includes HEIC, WebP, AVIF, and exotic video codecs. The fix in both cases is to convert before upload: convert images to JPG or PNG and video to MP4 using H.264. Check the actual codec and extension of the file, not just the filename, because a renamed file can still fail validation.
Video pin cover errors: cover_image_url and cover_image_content_type
The cover_image_url code means a video pin is missing the cover_image_url field. Pinterest video pins require a still cover image alongside the video file, so always include cover_image_url on video pins. The cover_image_content_type code means the cover image content type is missing or wrong. Pinterest needs an explicit image/jpeg or image/png declaration alongside the URL, and the declared type must match the actual file. Declare a supported MIME type and verify the file matches it.
Worked example: video pin with cover image and supported formats
For a video pin, prepare the video as MP4 using H.264, prepare a separate JPG or PNG cover image, and include both cover_image_url and cover_image_content_type in the pin payload. Set cover_image_content_type to image/jpeg for a JPEG cover or image/png for a PNG cover, and confirm the cover file matches that declaration. For an image pin, use JPG or PNG directly and no cover fields are needed. If a HEIC, WebP, or AVIF image is supplied, convert it to JPG or PNG first. If a video uses an exotic codec, convert it to MP4 H.264 first. Then check the failure matrix above if the request still fails, starting with authentication and rate limit before re-checking media and cover fields.
Quick reference table
Use the quick reference table below to look up any of the eight codes by name. Search for the exact code string in the response, note its category, and apply the matching fix from the failure matrix. Keeping this table open during pin creation debugging makes it faster to confirm whether a failure is authentication, rate limit, media, or video related.
| Code | Category | Cause | Fix |
|---|---|---|---|
| unauthorized | Authentication | Access token rejected; token expired after 30 days or user revoked app access | Reconnect and retry with a fresh token |
| invalid token | Authentication | Token format wrong or minted under a deleted Pinterest app | Check token format and originating app, then reconnect |
| 429 | Rate limit | Per-app or per-user request cap reached; caps reset hourly | Wait for the reset window or use exponential backoff |
| rate limit | Rate limit | Throttled by Pinterest through a different code path | Back off and reduce burst size |
| invalid media | Media | Media file not in a supported format; supported formats are JPG/PNG for images and MP4/MOV H.264 for video | Convert the file to a supported format before upload |
| unsupported format | Media | File extension or codec not on the allowlist, such as HEIC, WebP, AVIF, or exotic video codecs | Convert to JPG/PNG for images or MP4 H.264 for video |
| cover_image_url | Video | Video pin missing the required cover_image_url field | Always include cover_image_url on video pins |
| cover_image_content_type | Video | Cover image content type missing or wrong; Pinterest needs image/jpeg or image/png matching the file | Declare a supported MIME type and ensure the file matches |
| Code | Category | What it means |
|---|---|---|
| cover_image_url | Video | Video pin missing the cover_image_url field. |
| cover_image_content_type | Video | Missing or wrong content type on the cover image. |
| unauthorized | Authentication | Pinterest access token rejected. |
| invalid token | Authentication | Token failed validation. |
| 429 | Rate limit | Pinterest rate limit reached. |
| rate limit | Rate limit | Throttled by Pinterest. |
| invalid media | Media | Media file is not in a supported format. |
| unsupported format | Media | File extension or codec is not on Pinterest's allowlist. |
{
"cover_image_url": "{{COVER_IMAGE_URL}}",
"cover_image_content_type": "image/jpeg"
}