> ## Documentation Index
> Fetch the complete documentation index at: https://www.dropfans.io/developers/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> HTTP status meanings and the (deliberately honest) catalogue of body shapes you will see.

- Source: https://www.dropfans.io/developers/concepts/errors
- Section: Concepts
- OpenAPI: https://www.dropfans.io/developers/openapi.json

The API grew endpoint by endpoint, and its error bodies are not uniform. Rather than pretend otherwise, here is the exact catalogue — what each status means and every shape a body can take.

## Status codes

| Status | Meaning |
| --- | --- |
| `400` | Validation failed — a missing field, a bad value, malformed JSON, or a prohibited word on drop fields. |
| `401` | Missing, malformed or revoked API key. |
| `403` | The key works but the request is not allowed: not a creator account (posts), a resource you do not own (previews), a suspended app (`app_suspended`), or an expired video-upload token. |
| `404` | Resource not found — including resources that exist but belong to another creator (deliberately indistinguishable). |
| `409` | Conflict: duplicate folder name, a video upload that has not finished (retry), or a creator with no username on [GET /links](https://www.dropfans.io/developers/reference/get-links.md). |
| `413` | Upload too large — see [Upload media](https://www.dropfans.io/developers/guides/upload-media.md) for the caps. |
| `422` | A post caption tripped the prohibited-word filter. |
| `429` | Rate limited, or the daily posting cap — see [Rate limits](https://www.dropfans.io/developers/concepts/rate-limits.md). |
| `500` | Our fault. Retry with backoff; if it persists, tell support@dropfans.io. |

## Error body shapes

| Shape | Where |
| --- | --- |
| `{ "error": "…" }` | The baseline — human-readable prose, everywhere not listed below. |
| `{ "error": "…", "code": "…" }` | Gateway errors: `401` (`unauthorized`), `403` (`app_suspended`, `first_party_only`), `429` (`rate_limited`), and `409` (`username_required` on links). When a `code` is present, branch on it — the prose can change, the code will not. |
| `{ "error": "…", "matchedWord": "…" }` | `422` from [POST /posts](https://www.dropfans.io/developers/reference/create-post.md) — the caption word that tripped the filter. |
| `{ "error": "…", "field": "…", "matchedWord": "…" }` | `400` from [POST /drops](https://www.dropfans.io/developers/reference/create-drop.md) — which field (`name` or `description`) tripped it, and on what word. |
| `{ "error": "Invalid JSON body" }` | `400` from any JSON endpoint when the body does not parse. |

## Success envelopes

Successes are not uniform either:

| Shape | Where |
| --- | --- |
| Bare object | `GET /me`, `GET/PUT /timezone`, `GET /balance`, `GET /earnings`, `GET /links`, `GET /posts/{id}`, `POST /posts` (201), `POST /drops`, `POST /vault/folders`, and both list endpoints. |
| `{ "success": true, … }` | Vault writes (`DELETE /vault/{id}`, folder move, tags, folder delete, uploads), `POST /drops/{id}/previews`, notification settings. |
| `{ "ok": true }` | `DELETE /posts/{id}`. |
| Keyed map | The batch endpoints: `POST /vault/video-status` → `{ "statuses": { … } }`, `POST /drops/check-status` → `{ "sales": { … } }`. |

> [!IMPORTANT] Batch endpoints omit, they don’t error
> `video-status` and `check-status` leave out ids they cannot resolve — unknown, unowned, or unpaid — instead of failing the call. A missing key in the result map is an answer, not an error.

Every reference page lists its exact error rows — see the [API reference](https://www.dropfans.io/developers/reference/overview.md).

Next: [Pagination & batch limits](https://www.dropfans.io/developers/concepts/pagination.md) or [Rate limits](https://www.dropfans.io/developers/concepts/rate-limits.md).

---

Previous: [Rate limits](https://www.dropfans.io/developers/concepts/rate-limits.md) · Next: [Pagination & batch limits](https://www.dropfans.io/developers/concepts/pagination.md) · All pages: [llms.txt](https://www.dropfans.io/developers/llms.txt)