Skip to main content
When the API returns an error, the response body always has the same shape. The code field is a stable, machine-readable identifier — match on it instead of the human message, which can change. Each error’s doc_url links straight to its entry on this page.
New to handling our errors? Start with the Error handling guide for the response shape, how to catch errors, and how to respond to each error type.

​
Authentication and access

​
authentication_required

401 — Your Authorization header is missing or invalid. Send your API key as a Bearer token: Authorization: Bearer mk_live_…. See Authentication.

​
SOCIAL_TOKEN_EXPIRED

401 — The connected social account needs to be reconnected (its token expired or was revoked). Reconnect the account in Social Connections, then retry. 400 — The one-time sign-in link expired or was already used, usually because the user took too long on the platform’s consent screen. Nothing is wrong with the account. Start the connection again and confirm right away.

​
SOCIAL_CONNECT_FAILED

400 — We couldn’t finish connecting a social account, for a reason other than an expired link (a permission the user didn’t grant, or a problem on the platform’s side). The message says which. Start the connection again.

​
permission_denied

403 — Your key is valid but can’t access this resource. Usually the business doesn’t belong to your organization, or your plan doesn’t include API access. Check the business ID and your org’s plan.

​
INVALID_API_KEY

422 — A third-party key you supplied (for example an OpenRouter or Gemini key) isn’t valid. Check the key and save it again.

​
Invalid requests

​
validation_error

422 — The request body failed validation. The param field names the first offending field; if several fields failed, read error.details for the full list.

​
missing_field

400 — A required field is missing. The param field tells you which one.

​
invalid_value

400 — A field has a value that isn’t allowed. Check param and message for the specifics.

​
invalid_request

400 — The request couldn’t be processed and no more specific code applies. Read message for the reason.

​
resource_not_found

404 — The ID doesn’t exist, was deleted, or doesn’t belong to your organization. Check the ID and try again.

​
already_exists

409 — A resource with that name or ID already exists. Use a different value.

​
Plans, billing, and credits

​
PAYMENT_REQUIRED

402 — This feature needs a paid plan. Upgrade to use it.

​
INSUFFICIENT_CREDITS

402 — Your organization is out of credits. The response includes required_credits so you can show how many more are needed. Add credits or upgrade, then retry.

​
BUSINESS_CREDIT_LIMIT_EXCEEDED

402 — The workspace hit a monthly credit cap set by the org admin (different from running out of credits). The admin needs to raise the cap. A sub-account can’t self-serve here.

​
CHECKOUT_BLOCKED

400 — Recent payment attempts were flagged by our payment processor, so checkout is blocked. Contact support to continue.

​
SUBSCRIPTION_ALREADY_ACTIVE

409 — The organization already has an active or trialing subscription, so there’s nothing to check out. Manage the plan in account settings instead.

​
Limits and quotas

​
rate_limit_exceeded

429 — You sent too many requests. Back off and retry. These response headers are sent on every API-key response (including the 429 itself, so a throttled client always learns when to retry):

​
limit_exceeded

400 — A resource cap was reached (for example, the max number of webhooks or API keys per org). Delete something you no longer use to free up room.

​
storage_limit_exceeded

400 — The business hit its media storage limit. Delete unused media, or upgrade for more space.

​
WORKSPACE_LIMIT_EXCEEDED

400 — The organization reached the most workspaces its plan allows. Upgrade to add more.

​
WORKSPACE_NOT_SUPPORTED

400 — Your plan doesn’t support this workspace action.

​
FILE_TOO_LARGE

413 — The upload is over the size limit. Use a smaller file and try again.

​
Content and generation

​
NO_ENABLED_TOPICS

422 — The business has no topics turned on, so there’s nothing to generate from. Enable at least one topic first.

​
NO_CONNECTED_SOCIALS

400 — The business has no connected social account (or none of the requested platforms are connected), so there’s nothing to read from or publish to. Connect a social account first.

​
NOT_ENOUGH_POSTS_FOR_TOPICS

422 — There aren’t enough past posts to suggest topics from. Publish or import a few more posts, then try again.

​
PLATFORM_MEDIA_UNSUPPORTED

400 — The target platform doesn’t support this media type (for example, Google Business doesn’t accept video). Use a different file or platform.

​
PHONE_NOT_VERIFIED

400 — The action needs a verified phone number (for example, enabling SMS). Verify the phone first.

​
Server and upstream

​
internal_error

500 — Something went wrong on our end. Retry after a short delay. If it persists, submit feedback with the error details and the request ID.

​
UPSTREAM_PROVIDER_ERROR

502 — A third-party provider we depend on (a social platform, or a service like the SMS, email, transcription, or stock-media provider) failed. This is usually transient and not a problem with your request. Retry after a moment.