Events and limits
Errors
Every error is an HTTP status with a PascalCase code, a message and details. The full list of codes, what each means and how to fix it.
Every error answers with an HTTP status and one JSON envelope:
| Field | What it holds |
|---|---|
error |
A PascalCase code, such as PostValidationFailed. Branch on this, never on the message. |
message |
A sentence for people. Its wording can change. |
details |
Facts that help you fix the request, for the codes that have them: issues for validation, requiredScope for a missing scope, the current state for a conflict. |
requestId |
The id of the request, also sent in the X-Request-Id header. Quote it when you contact support. |
Validation
Unknown fields are refused, not ignored: a misspelt field answers 422 ValidationError naming it, so a typo never turns into a silently wrong post. A post that breaks a platform rule answers 422 PostValidationFailed, with every issue across every target in details.issues, and nothing is created.
Errors on a target
An error answer means the request itself was refused. Once a post is accepted, each target succeeds or fails on its own, and a failed target carries its own error with a code, a message and the action to take, such as reconnecting the account or fixing the media. Read those on the post, in the post.target.failed event or in the target's timeline.
Which errors to retry
- Wait and retry:
429 RateLimitedafterRetry-After,409 IdempotencyInProgresswith the sameIdempotency-Key, and the503codes after a short wait. - Fix, then retry: the
400and422codes, and409 DuplicateContentif you meant to post again. - Act first:
402 PaymentRequiredand402 PlanLimitReachedneed a billing change,409 AccountDisconnectedneeds the account connected again.
Error codes
Every code the operations in the API reference can answer is below, grouped by HTTP status, with what it means and how to fix it. Each code has its own anchor on this page, so a link to /docs/errors#<Code> lands on it.
HTTP 400
- InvalidJson
The request body is not valid JSON.
How to fix it: Send a well-formed JSON body, or no body at all when every field is optional.
- WorkspaceRequired
The request needs an X-Workspace-Id header.
How to fix it: Send the X-Workspace-Id header naming the workspace the request is for.
HTTP 401
- InvalidApiKey
The API key is unknown, revoked or malformed.
How to fix it: Check that the key is copied in full and has not been revoked; create a new key in the dashboard if needed.
- Unauthenticated
The request carries no valid credentials.
How to fix it: Send a valid API key or OAuth access token in the Authorization header as a Bearer token.
HTTP 402
- PaymentRequired
The workspace is past due and its grace period has ended.
How to fix it: Pay the open invoice linked in details.hostedInvoiceUrl (or in the dashboard billing settings), then retry.
- PlanLimitReached
The workspace reached a limit of its plan.
How to fix it: Check the workspace usage, wait for the next billing period or upgrade the plan before retrying.
HTTP 403
- CsrfRejected
A write made with a signed-in session lacked the X-Requested-With header.
How to fix it: Send X-Requested-With: XMLHttpRequest with every write made with a signed-in session, or use an API key.
- Forbidden
The credential is not allowed to do this.
How to fix it: Use a credential or role that allows this action; details.requiredScope names a missing scope, and details.action names the action the role does not allow.
- InviteEmailMismatch
The invite was sent to a different email address.
How to fix it: Sign in with the email address the invite was sent to, or ask for a new invite.
- ModuleNotAvailable
The module is not enabled for this workspace.
How to fix it: Enable the module for the workspace or move to a plan that includes it.
- WorkspaceSuspended
The workspace is suspended.
How to fix it: Contact support or a workspace owner to lift the suspension; nothing can run until then.
HTTP 404
- InviteInvalid
The invite is unknown, expired, revoked or already used.
How to fix it: Ask a workspace owner or admin to send a new invite.
- NotFound
The resource does not exist or is not visible to this credential.
How to fix it: Check the id and that the credential can see the resource; resources outside its brands are reported as not found.
HTTP 409
- AccountDisconnected
The account is disconnected; connect it again first.
How to fix it: Connect the account again before using it.
- Conflict
The request conflicts with the current state of the resource.
How to fix it: Read the resource again and retry with its current state.
- DuplicateContent
The same content was already published to this account.
How to fix it: Change the caption or media before publishing again to the same account.
- IdempotencyInProgress
A request with this Idempotency-Key is still running.
How to fix it: Wait for the first request with this Idempotency-Key to finish, then retry with the same key.
- MediaInUse
The media is attached to a post and cannot be deleted.
How to fix it: Detach the media from every post that uses it, then delete it.
- PostStateConflict
The post is in a state that does not allow this action.
How to fix it: Read the post again and only retry the action from a state that allows it, as listed in details.
- WorkspaceDeletionInProgress
The workspace is being deleted; wait for the deletion to finish.
How to fix it: Wait for the workspace deletion to finish; the workspace cannot change while it runs.
HTTP 413
- MediaTooLarge
The media file exceeds the size limit.
How to fix it: Compress or shorten the file so it fits the size limit, then upload it again.
- PayloadTooLarge
The request body exceeds the size limit.
How to fix it: Send a smaller body; details.maxBytes is the limit (with an Idempotency-Key, 1 MB for JSON and the upload size for files).
HTTP 415
- UnsupportedMediaType
The Content-Type is not a supported media type.
How to fix it: Send the file with a supported Content-Type such as image/jpeg or video/mp4.
HTTP 422
- IdempotencyKeyReused
The Idempotency-Key was used with different parameters.
How to fix it: Use a new Idempotency-Key for a request with different parameters.
- MediaRejected
The media file failed the platform media rules.
How to fix it: Convert the file to meet the platform media rules in details, then upload it again.
- PostValidationFailed
The post does not satisfy the rules of its platform.
How to fix it: Fix each issue in details.issues so the post meets the platform rules, then retry.
- UnsupportedAuthVariant
The platform does not support this sign-in variant.
How to fix it: Connect the account with a sign-in variant the platform supports.
- UnsupportedPlatform
The platform is not supported.
How to fix it: Use one of the platforms the API supports.
- ValidationError
The request is malformed or has an unknown or invalid field.
How to fix it: Fix the fields named in details.issues and send the request again; unknown fields are rejected.
HTTP 429
- RateLimited
Too many requests; wait for Retry-After.
How to fix it: Wait the number of seconds in Retry-After (details.retryAfter in a tool error), then retry.
HTTP 501
- NotSupported
The operation is not supported.
How to fix it: Use a supported alternative; this operation is not available.