Errors and limits
A Buzzmark API refusal is JSON with a code, a message, whether a retry may work, and a request id, and its HTTP status matches the code.
Each key has its own rate limit, apart from AI apps. A monthly plan quota that runs out answers 429 limit_reached, which waiting a minute doesn't fix.
Errors
A refusal is {"ok": false, "error": {"code", "message", "retryable", "request_id"}}. Build on code, show message to a person, and retry only when retryable is true. Every answer carries the same id in its X-Request-Id header: send it to support@buzzmark.ai when you ask about a request.
| Code | Status | Retry | What it means |
|---|---|---|---|
| bad_request | 400 | No | The body isn't JSON, or a query value can't be read. |
| idempotency_key_required | 400 | No | A POST that creates something needs an Idempotency-Key header. |
| unauthorized | 401 | No | No key, an unknown key, a revoked or expired key, or the key's maker left the organization. |
| forbidden | 403 | No | The key's scope or its maker's role doesn't allow this. |
| not_found | 404 | No | No such endpoint, or no such post, social set or account for this key. |
| method_not_allowed | 405 | No | The endpoint exists, with another method. |
| in_flight | 409 | Yes | A request with the same Idempotency-Key is still running. |
| invalid | 422 | No | The request was read and refused: a field is wrong, or the post breaks a platform's rules. |
| idempotency_mismatch | 422 | No | The Idempotency-Key was already used with another body. |
| rate_limited | 429 | Yes | The key's limit for the minute or the hour is used up. Retry-After says when. |
| limit_reached | 429 | No | A plan's own quota for this ran out. The message says what, and when it starts again. |
| failed | 502 | Yes | The posting queue or a platform didn't answer. Nothing was changed. |
| internal | 500 | Yes | Something went wrong on Buzzmark's side. Nothing was changed. |
Rate limit
Each key has its own limit, apart from AI apps:
| A minute | 60 |
|---|---|
| An hour | 1,000 |
Every answer carries RateLimit and RateLimit-Policy headers. Past the limit, the answer is 429 rate_limited with Retry-After in seconds.
Plan quotas
Writing, Hive checks, Scout runs and pictures use your plan's monthly amounts, as in the app. When one runs out, the answer is 429 limit_reached, saying which and when it starts again. It isn't retryable: waiting a minute doesn't bring it back.
| Plan | Growth | Reach | Scale | Agency |
|---|---|---|---|---|
| Brands Each brand is a social set with its own channels, slots and time zone. | 1 | 3 | 10 | 25 |
| Hive profiles How Buzz knows each brand's voice. | 1 | 3 | 10 | 25 |
| Connected channels | 5 | 20 | 50, then $2 each | 125 |
| Buzz written for you New writing Buzz does for you. One piece counts once, however many channels it goes to. | 75 a month | 300 a month | 600 a month | 1,500 a month |
| AI images | 20 a month | 100 a month | 200 a month | 500 a month |
| Scout runs Research on your competitors or the news in your field. | 3 a month | 15 a month | 60 a month | 150 a month |
| Hive checks A score for how much a draft sounds like you. Up to 8 on one post. | 225 a month | 900 a month | 1,800 a month | 4,500 a month |
| Seats | 1 | 5 | Unlimited | Unlimited |
| Engage: comments, DMs and Google reviews in one list Buzz sorts what needs you first and drafts each reply in your voice. Nothing goes out until you press Send. | Not included | Not included | Included | Included |
| X comments and messages X charges for every read. Reading a comment uses 1, a message 2, a reply you send 3. A one-off pack adds 2,000 for $29, kept until you use them. | Not included | Not included | 2,000 a month | 5,000 a month |
| Roles and approval before a post goes out | Not included | Included | Included | Included |
| Review links for clients, no account needed | Not included | Not included | Included | Included |
| Client reports | Not included | Not included | Included | Included |
| Connect links for a client's own accounts Your client signs in to each platform from a link, and the account lands in their brand. Nobody shares a password. | Not included | Not included | Included | Included |
| Teammates limited to chosen brands Each teammate sees and works on only the brands you pick for them. | Not included | Not included | Included | Included |
| Client portal One address per client with their content plan, feedback and reports. A client gets in with a code sent to their email, never a Buzzmark account. | Not included | Not included | Not included | Included |
| White label Your name, logo and colour on the portal, review links, connect links and reports, with no Buzzmark mark on them. The sign-in email comes under your agency's name. | Not included | Not included | Not included | Included |
| Scheduled client reports A weekly or monthly report, or a campaign's when it ends, emailed to the people on the client's portal under your agency's name. | Not included | Not included | Not included | Included |
| Campaigns with their own report | Not included | Not included | Not included | Included |
| Client setup in the portal Your client answers what shapes their voice: their stories, the posts they like, what they sell. Nothing reaches their Hive until you accept it. | Not included | Not included | Not included | Included |
Prices, in your currency: buzzmark.ai/pricing
Where to next
- Endpoints
Every endpoint of the Buzzmark REST API, with its method and path, the key scope it needs, its inputs and a curl example to copy into code, n8n or Make.
- Keys and scopes
A Buzzmark API key, made in Settings under Developers, has one scope: Read, Draft (reads too) or Schedule (reads and drafts too).
- Check and schedule posts
POST /posts/validate checks a post against each account's platform rules and saves nothing; POST /posts and POST /posts/bulk run the same check, then schedule.
- Plans and usage
Buzzmark has 4 plans, Growth, Reach, Scale and Agency, which differ in brands, accounts, seats and how much Buzz, the writer inside Buzzmark, makes for you each month.