> ## Documentation Index
> Fetch the complete documentation index at: https://docs.captureflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Every error code, what it means and what to do.

Errors have one shape, in REST responses and MCP tool errors alike:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "workspace_required",
    "message": "You belong to several workspaces. Pass workspace_id.",
    "param": "workspace_id",
    "details": { "workspaces": [{ "id": "...", "name": "Acme" }] },
    "doc_url": "https://docs.captureflow.ai/api/errors#workspace_required",
    "request_id": "req_..."
  }
}
```

* `code` is stable: branch on it. `message` is for people and may change.
* `param` names the input at fault; `details` carries extra data where noted below.
* `request_id` (also the `X-Request-Id` header) identifies the call for support.
* Over MCP the same body comes back as a tool error, with `_meta.request_id`.

**Types**: `invalid_request_error` (400, 413, 422), `authentication_error` (401), `plan_error` (402), `permission_error` (403, 423), `not_found_error` (404), `conflict_error` (409), `rate_limit_error` (429), `api_error` (5xx).

## Invalid requests (400, 413, 422)

### validation\_failed

**400** · An input is missing or invalid; `param` names it. Fix the request; retrying it unchanged won't help.

### workspace\_required

**400** · You belong to several workspaces and none could be chosen. Pass `workspace_id`; `details.workspaces` lists the candidates. See [Workspaces](https://docs.captureflow.ai/guides/workspaces.md).

### credentials\_in\_url

**400** · A key or token was sent in the query string. Send it in the `Authorization` header, and revoke the one you sent: URLs end up in logs.

### idea\_not\_found

**400** · `idea_id` is not one of your ideas in this workspace.

### invalid\_url

**400** · The URL to import is not a valid public `http(s)` address.

### unsupported\_media\_type

**400** · This file type can't be uploaded; `details.allowed` lists the accepted types. Text goes through `POST /v1/inputs/text`, web pages through `POST /v1/inputs/url`.

### file\_too\_large

**400** · The file is over the limit for its kind; `details.max_bytes` gives it. See [File uploads](https://docs.captureflow.ai/guides/uploads.md#accepted-files).

### platform\_not\_supported

**400** · Publishing to that social platform through CaptureFlow is not supported yet.

### unknown\_platform

**400** · A key of `platform_variations` is not a platform CaptureFlow knows (for example `instagram`, `twitter`, `facebook`, `tiktok`, `youtube`).

### body\_too\_large

**413** · The request body is over 100 KB. Send files through [uploads](https://docs.captureflow.ai/guides/uploads.md).

### url\_unreadable

**422** · The web page could not be read (unreachable, blocked, or no readable text).

### preflight\_failed

**422** · The post breaks a platform rule (length, media, format); `details.issues` lists what to fix. `POST /v1/posts/{id}/preflight` checks without proposing.

### size\_mismatch

**422** · The uploaded file is not the size declared when the upload was created. The upload is failed: start a new one.

### file\_type\_mismatch

**422** · The uploaded file is not of the declared type (checked from its content). The upload is failed: start a new one with the right `content_type`.

### file\_unprocessable

**422** · The file could not be processed (corrupt, or an image too large to handle). The upload is failed.

### processing\_failed

**422** · The upload could not be completed after several attempts. The upload is failed: start a new one, and contact support with the `request_id` if it happens again.

## Authentication and plans (401, 402)

### unauthorized

**401** · The key or token is missing, unknown, revoked or expired. Connected apps refresh their token or sign in again; the `WWW-Authenticate` header points to the OAuth metadata.

### plan\_required

**402** · This workspace has no paid plan or trial. An owner can choose a plan in CaptureFlow; `details.upgrade_url` links there (not in ChatGPT).

## Permissions (403, 423)

### insufficient\_scope

**403** · The credential lacks the permission this call needs; `details.required_scopes` names it, as does the `WWW-Authenticate` challenge. Connected apps ask the user for it; API keys need a new key. See [Scopes](https://docs.captureflow.ai/guides/scopes.md#asking-for-more-step-up).

### workspace\_locked

**403** · The key is locked to another workspace.

### api\_disabled

**403** · API & MCP access is switched off for this workspace. An owner or admin can switch it on in **Settings > API & MCP**.

### as\_user\_forbidden

**403** · Only an owner or admin, with an API key, can act as another member of the same workspace.

### viewer\_read\_only

**403** · Viewers have read-only access to the workspace.

### managed\_member\_restricted

**403** · In an agency client workspace, the agency creates and edits posts; members review and accept them in CaptureFlow.

### read\_only\_endpoint

**403** · This is the read-only MCP server (`/mcp/readonly`): nothing can be changed through it. Use `https://mcp.captureflow.ai/mcp` for changes.

### platform\_not\_enabled

**403** · That social platform is not available in this workspace.

### agent\_disabled

**403** · The content agent is switched off for this workspace.

### deletion\_pending

**423** · The account or workspace is scheduled for deletion. Nothing can be done through the API until the deletion is cancelled in CaptureFlow.

## Not found (404)

### not\_found

**404** · The object doesn't exist, or isn't yours. Also returned for an unknown path.

### workspace\_not\_found

**404** · The workspace doesn't exist, or you're not a member.

## Conflicts (409)

### conflict

**409** · The object changed in a way that prevents this call. Read it again and retry if it still makes sense.

### idempotency\_conflict

**409** · This `Idempotency-Key` was used for a different request. Use a new key for a new action.

### idempotency\_in\_progress

**409** · The first request with this `Idempotency-Key` is still running. Retry shortly with the same key.

### post\_not\_proposable

**409** · Only a draft (or a failed post) can be proposed; this one is already scheduled or published, or a proposal is already waiting. To change a waiting proposal, withdraw it (`DELETE /v1/posts/{id}/proposals`), then propose again.

### not\_proposed

**409** · The post is not waiting for acceptance, so there is no proposal to withdraw.

### post\_not\_editable

**409** · Only a draft (or a failed post) can be edited. If it is waiting for acceptance, withdraw the proposal first.

### post\_has\_variant

**409** · The post's text comes from a version chosen in CaptureFlow, so it can't be replaced through the API. Edit it in CaptureFlow.

### agent\_run\_in\_progress

**409** · A content agent run is still in progress; `details.run_id` names it. Wait for it to finish (`GET /v1/agent/runs/{id}`).

### too\_many\_pending\_uploads

**409** · Too many unfinished uploads; `details` says which limit. Complete them or let them expire.

### upload\_completed

**409** · The upload is already completed: there is nothing to upload. Its input is in the upload's `input`.

### upload\_failed

**409** · The upload failed earlier; `details.error_code` says why. Start a new upload.

### upload\_expired

**409** · The upload was not completed within 24 hours. Start a new one.

### upload\_in\_progress

**409** · Another request is completing this upload. Retry after `Retry-After` (also `details.retry_after_seconds`).

### object\_missing

**409** · The file has not arrived at the upload URL. PUT it, then complete again.

### object\_changed

**409** · The file was replaced while it was being checked. Complete again.

## Limits (429)

### rate\_limited

**429** · Too many requests. Wait `Retry-After` seconds. See [Rate limits](https://docs.captureflow.ai/guides/rate-limits.md).

### upload\_budget\_reached

**429** · The workspace used its daily upload allowance; `details` gives the limit. Try again later (`Retry-After`).

### agent\_daily\_limit

**429** · You started the most content agent runs allowed in a day in this workspace. Try again later.

### agent\_workspace\_limit

**429** · The workspace reached its daily limit of background agent runs. Try again later.

## Our side (5xx)

### internal\_error

**500** · Something went wrong on our side. Retry; if it keeps happening, contact support with the `request_id`.

### api\_unavailable

**503** · The API is not available right now.

### writes\_unavailable

**503** · Changes through the API are paused; reads still work. Retry later.

### storage\_unavailable

**503** · File storage is unavailable right now. Retry after `Retry-After`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.