# Errors and status codes

> Every response uses the same JSON envelope. Errors return a readable message in error and a standard HTTP status code.

**Source:** https://postprism.app/docs/errors  
**Updated:** 2026-10-10

---

## 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](https://postprism.app/docs/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](https://postprism.app/docs/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.