Errors and status codes
Every response uses the same JSON envelope. Errors return a readable message in error and a standard HTTP status code.
Last checked against the API October 10, 2026 · View as Markdown
Response envelope
Success
{ "data": { "id": "3f1c2a9e-0000-4000-8000-00000000a001", "status": "draft" }, "error": null }Error
{ "data": null, "error": "base_content and platforms are required." }Check the HTTP status first, then show error to a person or log it. DELETE returns 204 with no body. Messages name the field that failed, for example media[2].type must be "image" or "video".
Status codes
| Status | Meaning | What to do |
|---|---|---|
| 200, 201 | Success (201 when something was created) | Read data. |
| 204 | Deleted | Nothing to read. |
| 400 | The request is invalid | Fix the field named in error. Don’t retry unchanged. |
| 401 | Missing, malformed or revoked API key | Check the Authorization header. |
| 404 | The post or workspace was not found | Check the ID and workspace_id. |
| 413 | The file is too large | See Media requirements. |
| 415 | The file type is not accepted | Upload JPEG, PNG, GIF, WebP, MP4 or MOV. |
| 422 | The file contents don’t match its type, or can’t be read | Re-export the file and declare the right type. |
| 429 | Too many requests | Wait and retry. See Rate limits. |
| 500 | Something went wrong on our side | Retry with backoff; contact support if it persists. |
Error messages
| Status | Message | When |
|---|---|---|
| 400 | base_content and platforms are required. | base_content is empty or platforms is missing or empty. |
| 400 | media[0].url must be a URL returned by POST /api/v1/media. | A media URL was not uploaded through the API by you. |
| 400 | media accepts at most 10 items. | More than 10 files were attached. |
| 400 | platform_content.linkedin.media contains a URL that was not returned by POST /api/v1/media. | A per-platform media URL (or a YouTube thumbnailUrl) was not uploaded through the API. |
| 400 | platform_content.youtube.settings: YouTube title: YouTube titles are limited to 100 characters. | A platform setting failed validation. The message names the field. |
| 400 | Request body was empty. | No file was sent. |
| 400 | data is not valid base64. | JSON uploads only: data could not be decoded. filename, mime_type and data are all required. |
| 401 | Invalid or revoked API key | The Authorization header is missing, malformed, or the key was revoked. |
| 404 | Workspace not found, or you are not a member of it. | The workspace_id you passed (or your key’s default workspace) is not one you belong to. |
| 404 | Post not found | No post with that ID exists in the workspace. |
| 413 | File too large. Maximum is 10MB for images. | The file is over 10 MB (images or base64) or 100 MB (raw video). |
| 415 | Unsupported mime_type "image/svg+xml". Allowed: JPEG, PNG, GIF, WebP images; MP4, MOV videos. | The file type is not accepted. |
| 422 | File content is image/jpeg but was declared as image/png. | The bytes do not match the declared type, or the image could not be read. |
| 429 | Too many requests | You went over the hourly limit. See Rate limits. |
| 500 | Failed to delete post. | The post could not be deleted. Try again. |
Problems at publish time (a Pinterest post without an image, a disconnected account) don’t fail the API request. The post moves to
failed, and Postprism shows the reason on the post.