Errors - CaptureFlow API

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

{
  "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.

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.

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.

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.

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.

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.

​Invalid requests (400, 413, 422)

​validation_failed

​workspace_required

​credentials_in_url

​idea_not_found

​invalid_url

​unsupported_media_type

​file_too_large

​platform_not_supported

​unknown_platform

​body_too_large

​url_unreadable

​preflight_failed

​size_mismatch

​file_type_mismatch

​file_unprocessable

​processing_failed

​Authentication and plans (401, 402)

​unauthorized

​plan_required

​Permissions (403, 423)

​insufficient_scope

​workspace_locked

​api_disabled

​as_user_forbidden

​viewer_read_only

​managed_member_restricted

​read_only_endpoint

​platform_not_enabled

​agent_disabled

​deletion_pending

​Not found (404)

​not_found

​workspace_not_found

​Conflicts (409)

​conflict

​idempotency_conflict

​idempotency_in_progress

​post_not_proposable

​not_proposed

​post_not_editable

​post_has_variant

​agent_run_in_progress

​too_many_pending_uploads

​upload_completed

​upload_failed

​upload_expired

​upload_in_progress

​object_missing

​object_changed

​Limits (429)

​rate_limited

​upload_budget_reached

​agent_daily_limit

​agent_workspace_limit

​Our side (5xx)

​internal_error

​api_unavailable

​writes_unavailable

​storage_unavailable