APIErrors & pagination

Errors & pagination

Handle API errors, cursor pagination, and key scopes.

Error envelope#

Every unsuccessful request returns the same JSON shape. Read its hint for the next step, and include requestId if you contact support.

{
  "error": {
    "code": "invalid_request",
    "message": "accountIds must contain at least one account",
    "hint": "pass one or more IDs returned by GET /v2/accounts",
    "requestId": "req_01J..."
  }
}

Error codes#

Code	Meaning
unauthorized	The API key is missing, malformed, revoked, or invalid.
insufficient_scope	The key does not include the required scope.
invalid_request	The body, query, or path values failed validation.
account_not_found	The account does not exist or belongs to another company.
upload_not_ready	The upload has not finished processing.
media_not_ready	The existing post has no ready video or current rendered carousel media.
invalid_media_set	The media combination cannot form a supported post.
duplicate_queue_item	The same post is already queued for an account.
post_not_editable	The post has advanced beyond an editable status.
post_not_cancellable	No targeted item can be cancelled; released items may be in an operator's hands, and posted items cannot be deleted.
account_limit_reached	The company has used every account slot allowed by its plan.
rate_limited	A per-company UTC daily API, post, upload, or account-creation cap has been reached.
quota_exceeded	The company has reached a plan or posting limit.
file_too_large	The uploaded file exceeds the supported size.
unsupported_media_type	The file type or content type is not supported.
invalid_media_specs	The video failed codec, duration, dimension, or frame-rate validation.
invalid_cursor	The value used to get the next page is malformed or expired.

Every error includes a hint that says how to fix it. Endpoint-specific responses are also documented in the API Reference.

Getting more results#

List endpoints return up to 100 items at a time. When there are more, the response includes a nextCursor value. Send it back on the next request as ?cursor= to get the next page—you never need to build or understand this value. When nextCursor is null, you have everything.

# First page
GET /v2/posts?limit=25
→ { "data": [ 25 posts ], "nextCursor": "eyJj..." }

# Next page — pass nextCursor back exactly as received
GET /v2/posts?limit=25&cursor=eyJj...
→ { "data": [ 12 posts ], "nextCursor": null }   # null = no more pages

Scopes#

A key can only do what its scopes allow. Pick scopes when you create the key in the dashboard.

`posts:read`	List posts, inspect status, and read account queues.
`posts:write`	Upload media and create, queue, edit, or cancel posts.
`accounts:read`	List publishing accounts and inspect their details.
`accounts:write`	Create new TikTok and Instagram publishing accounts.
`analytics:read`	Read post and account performance analytics.
`usage:read`	View plan limits and daily API usage.

Need every field and option?

Browse every request field, response, option, and generated example in the interactive reference.

Open API Reference