Concepts
Errors
HTTP status meanings and the (deliberately honest) catalogue of body shapes you will see.
View as MarkdownUpdated Oct 26, 2026
Questions? [email protected]
HTTP status meanings and the (deliberately honest) catalogue of body shapes you will see.
Questions? [email protected]
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 | 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), an expired video-upload token, or an X-Dropfans-Account the key cannot act for (account_not_managed, permission_denied). |
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. |
413 | Upload too large — see Upload media for the caps. |
422 | A post caption tripped the prohibited-word filter. |
429 | Rate limited, or the daily posting cap — see Rate limits. |
500 | Our fault. Retry with backoff; if it persists, tell [email protected]. |
| Shape | Where |
|---|---|
{ "error": "…" } | The baseline — human-readable prose, everywhere not listed below. |
{ "error": "…", "code": "…" } | Gateway errors: 401 (unauthorized), 403 (app_suspended, first_party_only, api_category_disabled with an extra category field — see API categories), 429 (rate_limited), and 409 (username_required on links); the agency header and endpoints (invalid_account_header, account_not_managed, permission_denied with an extra permission field, account_header_not_allowed, agency_key_required); and the newer endpoints, which give most errors a code. When a code is present, branch on it — the prose can change, the code will not. |
{ "error": "…", "matchedWord": "…" } | 422 from POST /posts — the caption word that tripped the filter. |
{ "error": "…", "field": "…", "matchedWord": "…" } | 400 from POST /drops — 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. |
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": { … } }. |
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.
Next: Pagination & batch limits or Rate limits.