AxonFlow Agent API (11.0.0)

Invalid request body or parameters

Missing or invalid authentication. Handler-written 401s use the {success, error} envelope; 401s written by the auth middleware use the {"error": {"code", "message"}} envelope (JSONError).

A configured cost budget blocks the request (Enterprise cost controls; blocked: true, policy_info.matched_policies ["budget_exceeded"]), or, on Enterprise, the licence's ceiling refuses the client's service principal or the verified user token's principal at authentication (error names the refusal). Both bodies are a ClientResponse.

Request refused by the anchored engine. block_reason is the refusal's reason code (for example explicit_constraint) and policy_info.matched_policies names the policy that decided it, first. Since v11.0.0 no refusal on this route comes from another engine, and none is an approval hold (#4253).

Internal server error

The anchored engine could not decide the request (for example, no enforcer is wired in the process). The route fails CLOSED and never falls back to another engine: blocked is true and policy_info.matched_policies is ["decision_enforcement_unavailable"].

Invalid request body or parameters

Missing or invalid authentication. Handler-written 401s use the {success, error} envelope; 401s written by the auth middleware use the {"error": {"code", "message"}} envelope (JSONError).

The anchored engine could not decide the preview (for example, no enforcer is wired in the process): blocked is true and triggered_policies is ["decision_enforcement_unavailable"].

Invalid request body or parameters

Invalid request body or parameters

Missing or invalid authentication. Handler-written 401s use the {success, error} envelope; 401s written by the auth middleware use the {"error": {"code", "message"}} envelope (JSONError).

Budget exceeded — a configured cost budget blocks this request (Enterprise cost controls).

Access denied by policy or tenant mismatch

Community SaaS tenants past the daily request cap (written by the auth middleware; shared rate-limit envelope).

Circuit breaker is open — an emergency stop matching this request's scope is active.

Invalid or expired context

Missing or invalid authentication. Handler-written 401s use the {success, error} envelope; 401s written by the auth middleware use the {"error": {"code", "message"}} envelope (JSONError).

Request malformed (invalid JSON or missing required fields).

Authentication failed. THREE distinct causes, and the audit row distinguishes them even though the status code does not.

1. Credentials. In non-community mode the Authorization header is required and credentials must resolve to a valid client.
2. user_token_rejected -- a user_token WAS supplied in the request body and failed to validate (malformed, expired, wrong algorithm, bad signature, or revoked by jti). The attempt is audited as a blocked decision rather than being refused invisibly. Independent of any org posture.
3. user_token_required (#3476) -- NO user_token was supplied and the caller's organisation requires one. Off by default: this cause cannot occur unless an operator has set organizations.require_user_token for that organisation, or the deployment-wide AXONFLOW_REQUIRE_USER_TOKEN default. With the posture off, a token-less enterprise caller is served under a synthetic service identity exactly as before, which is the correct answer for an infrastructure gateway acting as a PEP with no end-user token to forward.

Causes 2 and 3 are recorded as reserved identifiers in the audit row's policy ids and MUST NOT be collapsed into one: they have opposite operator remedies (repair the caller's token, versus provision one at all). Query them with JSONB containment against policy_details->'policy_ids', never with LIKE -- _ is a single-character wildcard, so a %user_token_required% pattern also matches unrelated prose in the same row.

A per-user token is read from the user_token field of the request body on this endpoint. It is not read from the X-User-Token header here; that header belongs to a different envelope.

Tenant assertion mismatch -- caller_identity.tenant_id or caller_identity.org_id in the body did not match the authenticated identity (non-community mode only).

Token tenant mismatch -- the tenant of the resolved per-user token differs from the client's tenant. The canonical row records it with security_event tenant_mismatch.

segment_resolution_failed is no longer a cause (it was one from #3456). No segment gate stands here any more. It resolved the caller's governance segments and refused the request when that failed, on behalf of an organization's segment-scoped static rows, and those rows no longer decide: the anchored engine authors this verdict and reads no segments (PRD v11 §1.1, §1.2).

Community SaaS tenants past the daily request cap. Only emitted on the SaaS surface; self-hosted Community and Enterprise deployments do not return 429. The 429 is written by the auth middleware before the decide handler runs, so the body is the shared rate-limit envelope — NOT the DecideErrorResponse shape.

Circuit breaker is open. The body carries verdict: "deny" as the fail-closed default; a fail-open PEP adapter should treat 5xx as "PDP degraded" and apply its configured posture per ADR-056 §Failure posture. A Retry-After header is included when the breaker has a scheduled expiration.

Missing or invalid authentication. Handler-written 401s use the {success, error} envelope; 401s written by the auth middleware use the {"error": {"code", "message"}} envelope (JSONError).

MCP registry not initialized

Missing or invalid authentication. Handler-written 401s use the {success, error} envelope; 401s written by the auth middleware use the {"error": {"code", "message"}} envelope (JSONError).

Connector not found within the caller's tenancy. Returned both for a name that does not exist and for a name that belongs to another tenant.

MCP registry not initialized

Invalid request body or parameters

Missing or invalid authentication on an MCP REST route. FOUR distinct causes; the status code is the same for all four, and the audit row is what distinguishes the last two.

1. Credentials. No usable Basic auth / license credential.
2. A tenant the credential may not act for.
3. user_token_rejected -- a user_token WAS supplied in the request body and failed to validate: malformed, expired, signed with the wrong algorithm, carrying a bad signature, or revoked by jti. This is new behaviour on these four routes. Previously ANY user-token failure in enterprise mode was answered by synthesizing a service identity and serving the request, so revocation and expiry had no effect here; a presented token that fails to validate is now a refused access attempt, audited and returned as 401. This is not opt-in and no flag restores the old behaviour.
4. user_token_required (#3476) -- NO user_token was supplied and the caller's organisation requires one. Off by default; this cause cannot occur unless an operator has set organizations.require_user_token for that organisation, or the deployment-wide AXONFLOW_REQUIRE_USER_TOKEN default. With the posture off, a token-less enterprise caller is still served under a synthetic service identity, which is the correct answer for an infrastructure gateway that has no end-user token to forward.

Causes 3 and 4 are recorded as reserved identifiers in the audit row's policy ids and MUST NOT be collapsed: they have opposite operator remedies (repair the caller's token, versus provision one at all). Query them with JSONB containment against policy_details->'policy_ids', never with LIKE -- _ is a single-character wildcard, so a %user_token_required% pattern also matches unrelated prose in the same row.

These routes read the per-user token from the user_token field of the request body. They do not read the X-User-Token header; that header belongs to the MCP-server JSON-RPC envelope.

Handler-written 401s use the {success, error} envelope; 401s written by the auth middleware use the {"error": {"code", "message"}} envelope (JSONError).

Access denied. Causes on these routes:

• Tenant mismatch, or a connector this tenant may not access.

segment_resolution_failed is no longer a cause (it was one from #3447). No segment gate stands on these routes any more: the anchored engine reads no segments, as on decide.

Connector not found

Internal server error

Invalid request body or parameters

Missing or invalid authentication on an MCP REST route. FOUR distinct causes; the status code is the same for all four, and the audit row is what distinguishes the last two.

1. Credentials. No usable Basic auth / license credential.
2. A tenant the credential may not act for.
3. user_token_rejected -- a user_token WAS supplied in the request body and failed to validate: malformed, expired, signed with the wrong algorithm, carrying a bad signature, or revoked by jti. This is new behaviour on these four routes. Previously ANY user-token failure in enterprise mode was answered by synthesizing a service identity and serving the request, so revocation and expiry had no effect here; a presented token that fails to validate is now a refused access attempt, audited and returned as 401. This is not opt-in and no flag restores the old behaviour.
4. user_token_required (#3476) -- NO user_token was supplied and the caller's organisation requires one. Off by default; this cause cannot occur unless an operator has set organizations.require_user_token for that organisation, or the deployment-wide AXONFLOW_REQUIRE_USER_TOKEN default. With the posture off, a token-less enterprise caller is still served under a synthetic service identity, which is the correct answer for an infrastructure gateway that has no end-user token to forward.

Causes 3 and 4 are recorded as reserved identifiers in the audit row's policy ids and MUST NOT be collapsed: they have opposite operator remedies (repair the caller's token, versus provision one at all). Query them with JSONB containment against policy_details->'policy_ids', never with LIKE -- _ is a single-character wildcard, so a %user_token_required% pattern also matches unrelated prose in the same row.

These routes read the per-user token from the user_token field of the request body. They do not read the X-User-Token header; that header belongs to the MCP-server JSON-RPC envelope.

Handler-written 401s use the {success, error} envelope; 401s written by the auth middleware use the {"error": {"code", "message"}} envelope (JSONError).

Access denied. Causes on these routes:

• Tenant mismatch, or a connector this tenant may not access.

segment_resolution_failed is no longer a cause (it was one from #3447). No segment gate stands on these routes any more: the anchored engine reads no segments, as on decide.

Internal server error

Invalid request body or parameters

Missing or invalid authentication on an MCP REST route. FOUR distinct causes; the status code is the same for all four, and the audit row is what distinguishes the last two.

1. Credentials. No usable Basic auth / license credential.
2. A tenant the credential may not act for.
3. user_token_rejected -- a user_token WAS supplied in the request body and failed to validate: malformed, expired, signed with the wrong algorithm, carrying a bad signature, or revoked by jti. This is new behaviour on these four routes. Previously ANY user-token failure in enterprise mode was answered by synthesizing a service identity and serving the request, so revocation and expiry had no effect here; a presented token that fails to validate is now a refused access attempt, audited and returned as 401. This is not opt-in and no flag restores the old behaviour.
4. user_token_required (#3476) -- NO user_token was supplied and the caller's organisation requires one. Off by default; this cause cannot occur unless an operator has set organizations.require_user_token for that organisation, or the deployment-wide AXONFLOW_REQUIRE_USER_TOKEN default. With the posture off, a token-less enterprise caller is still served under a synthetic service identity, which is the correct answer for an infrastructure gateway that has no end-user token to forward.

Causes 3 and 4 are recorded as reserved identifiers in the audit row's policy ids and MUST NOT be collapsed: they have opposite operator remedies (repair the caller's token, versus provision one at all). Query them with JSONB containment against policy_details->'policy_ids', never with LIKE -- _ is a single-character wildcard, so a %user_token_required% pattern also matches unrelated prose in the same row.

These routes read the per-user token from the user_token field of the request body. They do not read the X-User-Token header; that header belongs to the MCP-server JSON-RPC envelope.

Handler-written 401s use the {success, error} envelope; 401s written by the auth middleware use the {"error": {"code", "message"}} envelope (JSONError).

Input blocked by policy.

segment_resolution_failed is no longer a cause (it was one from #3447). No segment gate stands here any more: the anchored engine authors the request pass's verdict (PRD v11 §1.1) and reads no segments, as on decide.

unsupported_obligation: a redaction this route cannot discharge (#4264). Under an organization's pii=redact posture a permit composes a mandatory redaction of the request, and this route hands back only the statement (redacted_statement). The request pass also scans parameters, so when the statement carries none of what the redaction requires masking, or a parameter carries some of it too, nothing this route returns can discharge it: the request is refused with allowed: false and a block_reason that starts unsupported_obligation: and names the obligation, the policy that attached it and why. A redaction the platform could not attempt (no redaction engine installed, the policies unreadable, a requirement or detector the engine no longer holds) is a 503.

Unregistered content_type (ADR-056). The request named a content type that no registered detector handles. A canonical blocked audit row tagged content_type_unsupported is written before the error returns — the request is treated as blocked, not silently skipped.

The policy engine could not decide the request (for example, the organization's active policy document could not be read). The request is refused, never let through (PRD v11 §1.7).

Invalid request body or parameters

Missing or invalid authentication on an MCP REST route. FOUR distinct causes; the status code is the same for all four, and the audit row is what distinguishes the last two.

1. Credentials. No usable Basic auth / license credential.
2. A tenant the credential may not act for.
3. user_token_rejected -- a user_token WAS supplied in the request body and failed to validate: malformed, expired, signed with the wrong algorithm, carrying a bad signature, or revoked by jti. This is new behaviour on these four routes. Previously ANY user-token failure in enterprise mode was answered by synthesizing a service identity and serving the request, so revocation and expiry had no effect here; a presented token that fails to validate is now a refused access attempt, audited and returned as 401. This is not opt-in and no flag restores the old behaviour.
4. user_token_required (#3476) -- NO user_token was supplied and the caller's organisation requires one. Off by default; this cause cannot occur unless an operator has set organizations.require_user_token for that organisation, or the deployment-wide AXONFLOW_REQUIRE_USER_TOKEN default. With the posture off, a token-less enterprise caller is still served under a synthetic service identity, which is the correct answer for an infrastructure gateway that has no end-user token to forward.

Causes 3 and 4 are recorded as reserved identifiers in the audit row's policy ids and MUST NOT be collapsed: they have opposite operator remedies (repair the caller's token, versus provision one at all). Query them with JSONB containment against policy_details->'policy_ids', never with LIKE -- _ is a single-character wildcard, so a %user_token_required% pattern also matches unrelated prose in the same row.

These routes read the per-user token from the user_token field of the request body. They do not read the X-User-Token header; that header belongs to the MCP-server JSON-RPC envelope.

Handler-written 401s use the {success, error} envelope; 401s written by the auth middleware use the {"error": {"code", "message"}} envelope (JSONError).

Output blocked by policy (exfiltration limit exceeded or SQLi detected).

segment_resolution_failed is no longer a cause (it was one from #3447). The route resolved the caller's governance segments and refused the request when that failed, on behalf of an organization's segment-scoped static rows, and those rows no longer decide: the anchored engine authors this verdict and reads no segments (PRD v11 §1.1, §1.2). So the shared engine's detector pass runs with no segment set, and a segment resolution that would fail changes nothing.

MCP registry not initialized

No usable credential. Written by the auth middleware as JSONError (platform/agent/auth.go:602), or — when the middleware admitted the caller but resolved no tenancy — by the handler as ErrorResponse (platform/agent/connector_refresh_api.go:148).

Refresh failed

Registry not initialized

Missing tenant_id

No usable credential. Written by the auth middleware as JSONError (platform/agent/auth.go:602), or — when the middleware admitted the caller but resolved no tenancy — by the handler as ErrorResponse (platform/agent/connector_refresh_api.go:148).

The {tenant_id} path segment does not match the authenticated tenant (platform/agent/connector_refresh_api.go:152-156). Refused rather than silently downgraded to the caller's own scope, so an operator who mistypes a tenant learns about it.

Refresh failed

Registry not initialized

Missing required parameters

No usable credential. Written by the auth middleware as JSONError (platform/agent/auth.go:602), or — when the middleware admitted the caller but resolved no tenancy — by the handler as ErrorResponse (platform/agent/connector_refresh_api.go:148).

The {tenant_id} path segment does not match the authenticated tenant (platform/agent/connector_refresh_api.go:152-156).

Refresh failed

Registry not initialized

No usable credential. Written by the auth middleware as JSONError (platform/agent/auth.go:602), or — when the middleware admitted the caller but resolved no tenancy — by the handler as ErrorResponse (platform/agent/connector_refresh_api.go:148).

Registry not initialized

Invalid request body or parameters

Missing or invalid authentication. Handler-written 401s use the {success, error} envelope; 401s written by the auth middleware use the {"error": {"code", "message"}} envelope (JSONError).

HITL approvals are disabled for the deployment's license tier. Entitled tiers are Professional, Enterprise and Enterprise Plus; Community, Free, Pro, Premium and Evaluation are refused (HITL became Enterprise-only on 2026-08-26; Evaluation was entitled until then). The refusal names no tier, because it is raised for five of them.

Community SaaS pending-approvals cap reached for the tenant. Not returned on self-hosted or Enterprise deployments.