General
Errors

The Capacities HTTP API signals outcome with standard HTTP status codes. Successful responses use 2xx. Responses in the 4xx range mean the request was not accepted (authentication, validation, permissions, rate limits, etc.). Responses in the 5xx range mean something failed on the server side.

Error responses use a consistent JSON body: a stable machine-readable code (always prefixed with cap_), a human-readable message, and optionally structured details for specific failure types.

Error response format

{
  "code": "cap_invalid_input",
  "message": "✖ Invalid input: expected string, received number\n  → at title"
}

Field	Type	Description
`code`	string	Stable identifier for programmatic handling. Values use the `cap_` prefix (for example `cap_not_authenticated`).
`message`	string	Human-readable explanation. For validation failures (`cap_invalid_input`), this is often a multi-line summary with field paths. Wording can change between API versions—use `code` to branch, not the exact `message` text.
`details`	optional	Structured context for certain codes only (for example missing OAuth scopes). Omitted when there is nothing extra to attach. Not used for validation errors.

Use code (and details when present) for programmatic handling. For cap_invalid_input, read message for debugging or displaying validation feedback to end users.

Error codes

Every published code is part of the API contract. Prefer matching on code in your integration and SDK.

`code`	Typical HTTP status	Meaning
`cap_not_authenticated`	`401`	Missing, invalid, or expired bearer token, or the token cannot be used for this request.
`cap_scope_insufficient`	`403`	The token does not include the scopes required for this operation.
`cap_not_found`	`404`	The requested resource does not exist or is not visible with this token.
`cap_invalid_input`	`400`, `413`	Request body, query, or parameters failed validation, or the payload is too large. Validation detail is in `message`.
`cap_rate_limit_exceeded`	`429`	Too many requests in the rate-limit window for this endpoint or token. See Rate limiting.
`cap_server_error`	`500`	An unexpected error occurred on the server. Retrying may succeed; contact support if it persists.
`cap_service_unavailable`	`503`	The service is temporarily unavailable (maintenance or overload). Retry with backoff.

The HTTP status and code are aligned: your client should treat (status, code) as the source of truth. Some edge responses may use a status that fits HTTP semantics (for example 413 Payload Too Large) while still using cap_invalid_input.

Validation errors (`cap_invalid_input`)

When request validation fails, the API responds with cap_invalid_input. The message field contains a readable multi-line summary (issue lines, often with → at <path> locations). There is no details field for validation—the formatted string is only in message.

Example (illustrative shape only):

{
  "code": "cap_invalid_input",
  "message": "✖ Required\n  → at title\n✖ String must contain at most 3000 characters\n  → at body.content"
}

Details for permissions (`cap_scope_insufficient`)

When the token is authenticated but lacks required scopes, details may include which scopes are missing:

{
  "code": "cap_scope_insufficient",
  "message": "The request requires additional API permissions.",
  "details": {
    "missingScopes": ["api:write"]
  }
}

Use missingScopes to prompt users to re-authorize or adjust API token permissions—not every response includes details if the situation is already clear from message.

HTTP status reference

Status	When it applies
`200`–`299`	Success.
`400`	Bad request / validation (often with `cap_invalid_input`).
`401`	Not authenticated (`cap_not_authenticated`).
`403`	Authenticated but not allowed—often scope-related (`cap_scope_insufficient`).
`404`	Not found (`cap_not_found`).
`413`	Request entity too large (`cap_invalid_input`).
`429`	Rate limited (`cap_rate_limit_exceeded`).
`500`	Server error (`cap_server_error`).
`503`	Service unavailable (`cap_service_unavailable`).

Rate limiting

429 responses use the same JSON shape; code is cap_rate_limit_exceeded. Check standard rate-limit headers (for example RateLimit-*) and Rate limiting for retry guidance.

TypeScript SDK

The @capacities/api client maps failed HTTP responses to CapacitiesApiError, with status, code, and optional details (for scope errors). For validation failures, inspect message. Prefer handling code rather than parsing free-text ad hoc.

Are you missing something in the documentation?

Create a ticket on our feedback board. - Let us know if you have an idea for a feature, improvement or think there is something missing.

Request additions to the documentation. - If your questions are not getting answered, let us know and we will extend the documentation.

Concurrency

Migration from Beta to v1

GeneralErrors

Errors