Concepts
Errors
HTTP status meanings and the (deliberately honest) catalogue of body shapes you will see.
View as MarkdownUpdated Aug 19, 2026
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. |
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]. |
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 — 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. |
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": { … } }. |
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.
Next: Pagination & batch limits or Rate limits.
Questions? [email protected]