Error codes
| Status | Meaning | Common cause |
|---|---|---|
400 |
Bad request | Malformed JSON; failed Zod validation. Large text fields are clamped server-side before validation, so 400s usually mean a missing or wrong-typed field, not size. |
401 |
Unauthorized | Missing X-API-Key / Authorization: Bearer; key revoked; key past expires_at. |
403 |
Forbidden | Authenticated but the key doesn’t carry the required scope. Brand publish needs posts:publish; article writes need articles:write. |
404 |
Not found | The id doesn’t exist or doesn’t belong to this user. |
409 |
Conflict | Duplicate active article: an article with the same source URL already exists in a non-archived state. Edit or archive the existing one. |
429 |
Too many requests | Rate limit hit. Back off and retry. |
5xx |
Server error | Transient; retry with exponential backoff. |
Error body
{ "error": "Invalid or missing API key" }
The error field is human-readable and safe to surface to end-users.
Related: Authentication