Errors

post.buzz uses standard HTTP status codes and one of two JSON error shapes. This page lists both shapes, the status-code table, and the catalog of machine-readable error.code values.

Error shapes

Structured shape (most /v1 errors)

{
  "error": {
    "code": "not_found",
    "message": "Post not found"
  }
}

• code — a stable, machine-readable string (see the catalog).
• message — a human-readable explanation.
• details — optional object; e.g. unknown_tool includes details.available listing valid tool names.

Legacy flat shape

A few older paths return a plain string under error:

{ "error": "Post not found" }

The legacy shape appears on:

• All authentication failures (401): "Missing API key", "Invalid API key", "API key expired".
• POST /v1/posts 400 (platform-limit violation) and 403 (foreign accountIds/mediaIds) — see Posts.
• DELETE /v1/posts/{id} 400 ("Cannot delete published post") and 404 ("Post not found").

Schema-validation 400

If the request fails the route's Zod/OpenAPI schema check (before the handler runs), the response is a 400 whose body is the validator's own serialization of the failed checks (field paths, expected vs. received types). Don't parse it with the structured-shape parser — treat any 400 without an error.code string as a schema/validation failure and inspect the field list.

Status codes

Status	Meaning	When
200	OK	Successful GET and every successful POST/PATCH/DELETE except post create
201	Created	Successful POST /v1/posts
400	Bad Request	Invalid input (schema or handler validation) or a platform-limit violation
401	Unauthorized	Missing, invalid, revoked, or expired API key (legacy flat shape)
403	Forbidden	No active/trialing subscription (subscription_required), or referenced accountIds/mediaIds not in your organization
404	Not Found	Resource doesn't exist or isn't in your organization (not_found)
409	Conflict	Deleting a team that still owns accounts (in_use)
413	Payload Too Large	Media upload above the effective size ceiling (too_large)
429	Too Many Requests	Insight-refresh cap, or the public AI tool's per-IP limit
500	Server Error	Unexpected failure (server_error)
502	Bad Gateway	URL-ingest fetch of your media failed (unreachable / server_error)
503	Unavailable	Database or object storage unavailable

Error-code catalog

Codes from the structured shape, with the statuses they accompany:

Code	Status	Meaning
validation_error	400	Handler-level input validation failed
unknown_tool	400	Unknown account tool; details.available lists valid ones
subscription_required	403	No active or trialing subscription on the key's organization
forbidden	403	Ownership/access failure (e.g. account not in the organization)
not_found	404	Resource missing or outside your organization
in_use	409	Team still owns accounts — move or remove them first
too_large	413	Media exceeds the effective plan/absolute size ceiling
rate_limited	429	Insight-refresh daily cap hit (message includes next slot)
server_error	500	Unexpected server-side failure
unreachable	502	Server-side fetch of a media URL failed
server_error (media)	502/503	Remote server errored / object storage unavailable

note

The media 502/503 codes overlap: unreachable means post.buzz could not fetch your URL; server_error on 502 means the remote returned an error; server_error on 503 means post.buzz's own object storage was unavailable.

Common errors by area

Authentication

Status	Body (error)
401	Missing API key
401	Invalid API key
401	API key expired

Posts

Status	Body
400	Legacy { "error": "<platform-limit message>" }
400	{ "error": "Cannot delete published post" }
403	Legacy { "error": "<ownership failure>" }
404	{ "error": { "code": "not_found", ... } } (get/patch/retry) or legacy { "error": "Post not found" } (delete)

System

Status	Body
503	{ "error": "Database not available" }
429	rate_limited — see Limits

Handling errors

• On 401, check that your API key is present, unrevoked, and unexpired.
• On 403 subscription_required, the organization needs an active plan — see Plans.
• On 400, inspect the field list (schema failure) or the message (platform-limit or handler validation) and adjust the request.
• On 403 (non-subscription), the account or media IDs you referenced are not in your organization — verify with GET /v1/accounts.
• On 429 rate_limited, the message tells you how many refreshes you've used and when the next slot opens; wait and retry.
• On 5xx, the failure is on our side; retry with backoff. These are rare.

Related

• REST API — request/response conventions.
• Limits — what triggers a limit 400/413/429.