{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "name": "SOAT API error codes",
  "version": "0.37.1",
  "description": "Every error code the SOAT REST API, MCP surface and SDK can return, with its HTTP status and what it means. Generated from the server source (packages/server/src/errors/codes.ts).",
  "shape": {
    "description": "Every 4xx and 5xx response body. `error.code` is a stable identifier safe to branch on; `error.message` is human-readable and may change; `error.hint` says what to do about the failure and `error.docs_url` addresses the reference section for the code; `error.meta` carries per-code context when available.",
    "example": {
      "error": {
        "code": "RESOURCE_NOT_FOUND",
        "message": "Project 'proj_abc123' not found.",
        "hint": "Check the id, and check that the credential can see the project that owns the resource — a resource in another project is indistinguishable from one that does not exist. List the collection to confirm.",
        "docs_url": "https://soat.ttoss.dev/docs/error-codes#resource_not_found"
      }
    }
  },
  "codes": [
    {
      "code": "ACTIVITY_INVALID_CURSOR",
      "http_status": 400,
      "description": "The activity feed cursor is malformed or does not decode to a valid (created_at, id) position.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#activity_invalid_cursor"
    },
    {
      "code": "ACTOR_HAS_MESSAGES",
      "http_status": 409,
      "description": "The actor has linked session messages and cannot be deleted.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#actor_has_messages"
    },
    {
      "code": "ACTOR_NOT_FOUND",
      "http_status": 400,
      "description": "A referenced actor does not exist.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#actor_not_found"
    },
    {
      "code": "AGENT_AND_CHAT_EXCLUSIVE",
      "http_status": 400,
      "description": "An actor cannot have both an agent_id and a chat_id assigned simultaneously. Set one or the other, not both.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#agent_and_chat_exclusive"
    },
    {
      "code": "AGENT_HAS_DEPENDENTS",
      "http_status": 409,
      "description": "The agent is referenced by one or more generations or traces and cannot be deleted. Delete the dependent records first.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#agent_has_dependents"
    },
    {
      "code": "AGENT_NOT_FOUND",
      "http_status": 400,
      "description": "A referenced agent does not exist.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#agent_not_found"
    },
    {
      "code": "AI_PROVIDER_ERROR",
      "http_status": 502,
      "description": "The upstream AI provider returned an error (e.g. insufficient credits, rate limit, or the provider is unreachable).",
      "resolution": "The upstream model provider failed, not this server. Check the provider credential and the account behind it (credits, rate limits, model access), then retry with backoff.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#ai_provider_error"
    },
    {
      "code": "AI_PROVIDER_HAS_DEPENDENTS",
      "http_status": 409,
      "description": "The AI provider still has dependents. Live references (chats, agents, model-route targets) always block deletion and must be deleted or repointed first. Soft dependents (price overrides, usage records) block only until force=true, which drops the overrides and unlinks usage history. The error meta reports the counts, a sample of offending IDs, and a `forcible` flag.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#ai_provider_has_dependents"
    },
    {
      "code": "AI_PROVIDER_MISCONFIGURED",
      "http_status": 400,
      "description": "The AI provider record is missing configuration the provider type requires — for example a `vertex` provider with no Google Cloud project in `config.project` and no service-account key file linked as its secret.",
      "resolution": "The provider record is missing something it needs to make a call — usually the API key secret or the base URL. Update the AI provider and retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#ai_provider_misconfigured"
    },
    {
      "code": "AI_PROVIDER_NOT_FOUND",
      "http_status": 400,
      "description": "A referenced AI provider does not exist.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#ai_provider_not_found"
    },
    {
      "code": "API_KEY_PROJECT_SCOPE",
      "http_status": 403,
      "description": "The credential (API key or OAuth token) is bound to one project and the request targets a different one. This project binding is a hard boundary that the owner’s admin role does not lift — admin only relaxes the project create/delete gate, never the per-credential project scope for resource operations. Mint a key scoped to the target project (or an unscoped key) to operate there. The error meta reports `scoped_project` and `requested_project`.",
      "resolution": "This API key is scoped to a single project and the request targets another one (or none). Omit `project_id` to use the key's own project, or use an unscoped credential.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#api_key_project_scope"
    },
    {
      "code": "APPROVAL_ALREADY_RESOLVED",
      "http_status": 409,
      "description": "The approval item has already been resolved (approved, rejected, or expired) and cannot be resolved again.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#approval_already_resolved"
    },
    {
      "code": "APPROVAL_EXPIRED",
      "http_status": 409,
      "description": "The approval item has expired and can never execute. Its supporting evidence is stale; a fresh proposal is required.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#approval_expired"
    },
    {
      "code": "APPROVAL_INVALID_EDIT",
      "http_status": 400,
      "description": "The edited arguments supplied on edit-then-approve must be a JSON object.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#approval_invalid_edit"
    },
    {
      "code": "APPROVAL_NOT_FOUND",
      "http_status": 404,
      "description": "The approval item does not exist or is not accessible.",
      "resolution": "Check the id and the project the credential can see, then retry. Listing the collection confirms whether the resource exists.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#approval_not_found"
    },
    {
      "code": "APPROVAL_REASON_REQUIRED",
      "http_status": 400,
      "description": "A reason is required when rejecting an approval item.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#approval_reason_required"
    },
    {
      "code": "BOOTSTRAP_ALREADY_COMPLETED",
      "http_status": 409,
      "description": "The instance already has at least one user, so the one-time bootstrap of the first admin cannot run again.",
      "resolution": "The first admin already exists, so bootstrap is closed for good. Sign in instead, and create further users with `POST /api/v1/users`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#bootstrap_already_completed"
    },
    {
      "code": "CHAIN_NOT_FOUND",
      "http_status": 404,
      "description": "The continuation chain does not exist or is not accessible.",
      "resolution": "Check the id and the project the credential can see, then retry. Listing the collection confirms whether the resource exists.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#chain_not_found"
    },
    {
      "code": "CHAT_NOT_FOUND",
      "http_status": 400,
      "description": "A referenced chat does not exist.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#chat_not_found"
    },
    {
      "code": "CONVERTER_FAILED",
      "http_status": 422,
      "description": "The ingestion converter (tool or agent) failed to run, an agent converter returned an async deferral (unsupported — agent converters are always awaited inline), or a tool converter returned an async deferral during synchronous ingestion (`?wait=true`, which cannot wait for a callback).",
      "resolution": "The request was accepted and then could not be carried out. The failure is in the work, not the request shape — read `meta` and the trace for which step failed before retrying.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#converter_failed"
    },
    {
      "code": "CONVERTER_OUTPUT_INVALID",
      "http_status": 422,
      "description": "The ingestion converter returned an unrecognized output shape. Expected a string, `{ pages: [{ text, page_number }] }`, or `{ status: \"pending\" }`.",
      "resolution": "The request was accepted and then could not be carried out. The failure is in the work, not the request shape — read `meta` and the trace for which step failed before retrying.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#converter_output_invalid"
    },
    {
      "code": "EMBEDDING_NOT_CONFIGURED",
      "http_status": 503,
      "description": "The embedding service is not configured. Set EMBEDDING_PROVIDER and EMBEDDING_MODEL environment variables.",
      "resolution": "Knowledge search needs an embedding model. Configure one on the project or the AI provider before ingesting or searching.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#embedding_not_configured"
    },
    {
      "code": "EXCEPTION_ALREADY_RESOLVED",
      "http_status": 409,
      "description": "The exception item has already been resolved and cannot be acknowledged or resolved again.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#exception_already_resolved"
    },
    {
      "code": "EXCEPTION_NOT_FOUND",
      "http_status": 404,
      "description": "The exception item does not exist or is not accessible.",
      "resolution": "Check the id and the project the credential can see, then retry. Listing the collection confirms whether the resource exists.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#exception_not_found"
    },
    {
      "code": "FILE_ALREADY_INGESTED",
      "http_status": 409,
      "description": "The file already backs a Document (a file can only be ingested once). Use POST /documents/{document_id}/ingest to re-process the existing document, or upload a new copy of the file to ingest it under a different path/strategy.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#file_already_ingested"
    },
    {
      "code": "FILE_DOWNLOAD_URL_NOT_CONFIGURED",
      "http_status": 500,
      "description": "An ingestion rule with file_delivery: download_url requires SOAT_BASE_URL to be set — the URL is fetched by an external converter that cannot resolve a relative or localhost address.",
      "resolution": "Retry with backoff. If it persists, the server log carries the detail the response deliberately omits.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#file_download_url_not_configured"
    },
    {
      "code": "FILE_HAS_DEPENDENTS",
      "http_status": 409,
      "description": "The file is referenced by one or more records and cannot be deleted. Delete the dependent records first.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#file_has_dependents"
    },
    {
      "code": "FILE_NOT_FOUND",
      "http_status": 400,
      "description": "The referenced file does not exist.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#file_not_found"
    },
    {
      "code": "FILE_PARSE_FAILED",
      "http_status": 400,
      "description": "The referenced file contains no extractable text.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#file_parse_failed"
    },
    {
      "code": "FILE_STORAGE_MISCONFIGURED",
      "http_status": 500,
      "description": "The file storage backend is not configured correctly — an unknown FILES_STORAGE_PROVIDER, an unsupported storage type, or a missing required variable (e.g. FILES_STORAGE_DIR for local, FILES_S3_BUCKET for s3).",
      "resolution": "Retry with backoff. If it persists, the server log carries the detail the response deliberately omits.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#file_storage_misconfigured"
    },
    {
      "code": "FILE_TOO_LARGE_FOR_SYNC",
      "http_status": 413,
      "description": "The file is too large to ingest synchronously. Retry without `?wait=true` to run ingestion in the background and poll the document status.",
      "resolution": "The file is too large to parse inside the request. Call the same operation without `wait=true` and poll the handle it returns.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#file_too_large_for_sync"
    },
    {
      "code": "FORBIDDEN",
      "http_status": 403,
      "description": "The authenticated user does not have permission to perform this action.",
      "resolution": "The credential authenticated but is not allowed this action. Attach an IAM policy granting the action to the caller, or use a credential that has it.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#forbidden"
    },
    {
      "code": "FORCED_TOOL_CHOICE_CANNOT_STOP",
      "http_status": 400,
      "description": "The agent forces tool use on every step (`tool_choice: \"required\"`, or the `{ type: \"tool\" }` object form) but declares no `has_tool_call` stop condition, so no turn it runs could ever end by answering — only by exhausting `max_steps`. Declare the terminal condition, or drop the forcing to `\"auto\"` and force a specific step with `step_rules` instead.",
      "resolution": "Add `{ \"type\": \"has_tool_call\", \"tool_name\": \"<your done tool>\" }` to `stop_conditions`, or set `tool_choice` to `\"auto\"` and force the step you actually care about with `step_rules`. `max_chain_generations` does not satisfy this — it bounds a chain, it never ends a turn.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#forced_tool_choice_cannot_stop"
    },
    {
      "code": "FORMATION_DELETE_FAILED",
      "http_status": 409,
      "description": "One or more of the formation's resources could not be deleted, so the stack is left in `delete_failed`. `meta.failures` names each blocking resource (its logical id, type, and the underlying error) — the common case is a resource the platform refuses to delete on its own, such as an agent that has generation or trace history. Resolve those, then delete the formation again.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#formation_delete_failed"
    },
    {
      "code": "FORMATION_HANDLER_FAILED",
      "http_status": 502,
      "description": "A resource type registered by the deployment operator delegates its lifecycle to an external HTTP handler, and that handler did not answer successfully — it returned a non-2xx status, timed out, was unreachable, or replied with a body the protocol does not allow (a create with no `physical_resource_id`, for instance). `meta.resource_type` and `meta.request_type` name the type and the operation, and the handler's own message is relayed when it sent one. This is an operator-side failure: the template is not at fault and re-deploying it unchanged will fail the same way until the handler is fixed.",
      "resolution": "A resource type this deployment registered delegates to an external handler, and that handler did not answer. The template is not at fault, so re-deploying it unchanged will fail identically — the deployment operator has to fix the handler (`meta.resource_type` names the type, `meta.request_type` the operation it failed on).",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#formation_handler_failed"
    },
    {
      "code": "FORMATION_INVALID_METADATA",
      "http_status": 400,
      "description": "The formation-level `metadata` field contains a `sub`/`param`/`ref`/`ref_attr` substitution expression. That field is a static annotation bag and is never resolved; put deploy-time substitutions in the template top-level `metadata` block instead.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#formation_invalid_metadata"
    },
    {
      "code": "FORMATION_MISSING_PARAMETERS",
      "http_status": 400,
      "description": "The formation template declares one or more required parameters (no default, not satisfied by use_previous_value) that were not supplied or were provided as an empty string.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#formation_missing_parameters"
    },
    {
      "code": "FORMATION_REPLACE_CLEANUP_FAILED",
      "http_status": 500,
      "description": "A deploy replaced a resource — the handler answered a new `physical_resource_id` — and the superseded resource could not be deleted, so it is still live while the formation's ledger already points at the replacement. The deploy itself succeeded: the desired state is realised, and this is carried on the formation (and on its operation) rather than thrown, so it never appears as a response status. `meta.failures` names each un-deleted resource as `{ logical_id, resource_type, physical_resource_id, error }`. Each one stays on the formation as pending cleanup and is retried on the next deploy and on teardown; resolve whatever refused the delete and deploy again.",
      "resolution": "Retry with backoff. If it persists, the server log carries the detail the response deliberately omits.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#formation_replace_cleanup_failed"
    },
    {
      "code": "GENERATION_ALREADY_IN_PROGRESS",
      "http_status": 409,
      "description": "A generation is already in progress for this session. Wait for it to complete before starting a new one.",
      "resolution": "A generation is already running for this target. Poll it to completion, or cancel it, before starting another.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#generation_already_in_progress"
    },
    {
      "code": "GENERATION_CONTENT_UNAVAILABLE",
      "http_status": 409,
      "description": "The generation's content was never stored (the agent or project runs with trace_content_mode 'none') or has since been purged, so the turn cannot be replayed or curated.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#generation_content_unavailable"
    },
    {
      "code": "GENERATION_FAILED",
      "http_status": 500,
      "description": "An unexpected error occurred during agent generation. Check the trace for details.",
      "resolution": "Retry with backoff. If it persists, the server log carries the detail the response deliberately omits.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#generation_failed"
    },
    {
      "code": "GENERATION_NOT_COMPLETED",
      "http_status": 409,
      "description": "The generation has not completed, so it has no finished turn to promote. Only a completed generation can be curated into a dataset item.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#generation_not_completed"
    },
    {
      "code": "GENERATION_NOT_FOUND",
      "http_status": 404,
      "description": "The generation does not exist or is not in a pending state for tool output submission.",
      "resolution": "Check the id and the project the credential can see, then retry. Listing the collection confirms whether the resource exists.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#generation_not_found"
    },
    {
      "code": "GUARDRAIL_HAS_REFERENCES",
      "http_status": 409,
      "description": "The guardrail is still attached to one or more tools, agents, or projects (`guardrail_ids`) and cannot be deleted. Detach every reference first (requires guardrails:DetachGuardrail). The error meta lists the referencing resources by scope.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#guardrail_has_references"
    },
    {
      "code": "GUARDRAIL_NOT_FOUND",
      "http_status": 400,
      "description": "A guardrail referenced by a `guardrail_ids` attachment does not exist in the project.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#guardrail_not_found"
    },
    {
      "code": "HOOK_INVALID_JSON",
      "http_status": 400,
      "description": "The inbound hook request body is not valid JSON.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#hook_invalid_json"
    },
    {
      "code": "HOOK_PAYLOAD_TOO_LARGE",
      "http_status": 413,
      "description": "The inbound hook request body exceeds the 1 MiB limit.",
      "resolution": "The payload exceeds the accepted size. Send less in one request, or use the upload flow for large bodies.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#hook_payload_too_large"
    },
    {
      "code": "INGESTION_CALLBACK_CONFLICT",
      "http_status": 409,
      "description": "The document is no longer awaiting this conversion attempt — it already completed, timed out, or was superseded by a re-ingest.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#ingestion_callback_conflict"
    },
    {
      "code": "INGESTION_CALLBACK_INVALID_TOKEN",
      "http_status": 401,
      "description": "The ingestion-callback token is missing, malformed, expired, or does not match the target document.",
      "resolution": "Authenticate the request: send a valid bearer token or project API key in the `Authorization` header.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#ingestion_callback_invalid_token"
    },
    {
      "code": "INGESTION_RULE_GLOB_CONFLICT",
      "http_status": 409,
      "description": "An ingestion rule for this content_type_glob already exists in the project.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#ingestion_rule_glob_conflict"
    },
    {
      "code": "INGESTION_RULE_VALIDATION_FAILED",
      "http_status": 400,
      "description": "The ingestion rule configuration is invalid (e.g. tool_id and agent_id are both set or both missing, the converter tool is a client tool, a soat/mcp converter tool is missing an action, content_type_glob is not a valid MIME type glob, or preset_parameters contains the reserved key \"file\" or \"callback\").",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#ingestion_rule_validation_failed"
    },
    {
      "code": "INTERNAL_ERROR",
      "http_status": 500,
      "description": "An unhandled server-side failure. The message is always the constant \"Internal Server Error\" — the underlying exception is logged, never returned, so this error carries no detail a caller can act on beyond retrying.",
      "resolution": "Retry with backoff. The underlying exception is logged server-side and deliberately never forwarded, so the response carries nothing further to act on.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#internal_error"
    },
    {
      "code": "INVALID_CRON_EXPRESSION",
      "http_status": 400,
      "description": "The cron expression is invalid. Triggers require a strict 5-field cron expression evaluated in UTC.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#invalid_cron_expression"
    },
    {
      "code": "INVALID_EVENT_PATTERN",
      "http_status": 400,
      "description": "The event pattern is invalid. An event trigger subscribes with '*', 'prefix.*', or an exact event name, and a pattern in a platform namespace must match a registered event.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#invalid_event_pattern"
    },
    {
      "code": "INVALID_OUTPUT_SCHEMA",
      "http_status": 400,
      "description": "The agent output_schema is invalid — it must be a JSON Schema object.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#invalid_output_schema"
    },
    {
      "code": "INVALID_TEMPLATE_TOKEN",
      "http_status": 400,
      "description": "A {{...}} double-curly token was found that is not a {{secret:sec_...}} or {{context:<key>}} reference, or a {{context:<key>}} token was found outside execute.headers / mcp.headers. Double curly braces are reserved for those two reference kinds; use single braces ({param}) for URL path parameters.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#invalid_template_token"
    },
    {
      "code": "INVALID_TOOL_CONTEXT_KEY",
      "http_status": 400,
      "description": "A tool_context key cannot be used as an HTTP header name. Keys are forwarded verbatim as <prefix><key> headers, where the prefix is the deployment's TOOL_CONTEXT_HEADER_PREFIX (X-Soat-Context- by default), so a key may only contain letters, digits and the characters !#$%&'*+-.^_`|~, and two keys must not map to the same header name (header names are case-insensitive).",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#invalid_tool_context_key"
    },
    {
      "code": "MISSING_TOOL_CONTEXT_KEY",
      "http_status": 400,
      "description": "A tool header references a {{context:<key>}} token whose key is not present in the tool_context for this call. The call is failed rather than sending the header with an empty value.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#missing_tool_context_key"
    },
    {
      "code": "MODEL_LISTING_FAILED",
      "http_status": 502,
      "description": "The provider rejected the model listing request, or answered it with something other than JSON. The provider's own status and message are carried in the error message.",
      "resolution": "An upstream dependency failed rather than this server itself. Retry with backoff and check that dependency.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#model_listing_failed"
    },
    {
      "code": "MODEL_LISTING_UNSUPPORTED",
      "http_status": 400,
      "description": "The AI provider type cannot enumerate the models it can run. Azure lists deployments an operator named rather than models, and Ollama lists whatever was pulled onto that host, so neither answers the question.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#model_listing_unsupported"
    },
    {
      "code": "MODEL_ROUTE_HAS_DEPENDENTS",
      "http_status": 409,
      "description": "The model route is referenced by one or more agents, or is a project's default_model_route_id, and cannot be deleted. Repoint or delete the referencing consumers first; the error meta reports the counts and a sample of agent IDs.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#model_route_has_dependents"
    },
    {
      "code": "MODEL_ROUTE_NOT_FOUND",
      "http_status": 400,
      "description": "A referenced model route does not exist in the project.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#model_route_not_found"
    },
    {
      "code": "NAME_CONFLICT",
      "http_status": 409,
      "description": "A resource with this name already exists in the project. Use a different name.",
      "resolution": "A resource with this name already exists in the project. Pick another name, or update the existing resource instead of creating a second one.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#name_conflict"
    },
    {
      "code": "NOT_IMPLEMENTED",
      "http_status": 501,
      "description": "The request is well-formed but names an option this API version does not implement.",
      "resolution": "The operation exists in the contract but is not implemented on this deployment. Retrying will not change the outcome.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#not_implemented"
    },
    {
      "code": "NO_ACTIVE_RELEASE",
      "http_status": 409,
      "description": "The agent has no active release to promote or abort. Set one with PUT /agents/{agent_id}/release first.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#no_active_release"
    },
    {
      "code": "ORCHESTRATION_CYCLE_DETECTED",
      "http_status": 422,
      "description": "The orchestration graph contains a cycle. Cycles are not supported.",
      "resolution": "The graph has a cycle, so no topological order exists. Break the cycle named in `meta` — a loop belongs in a workflow, not a DAG.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#orchestration_cycle_detected"
    },
    {
      "code": "ORCHESTRATION_DISPATCH_FAILED",
      "http_status": 422,
      "description": "A workflow on_enter dispatch's orchestration run settled in a non-success terminal status (failed, cancelled, or expired).",
      "resolution": "The request was accepted and then could not be carried out. The failure is in the work, not the request shape — read `meta` and the trace for which step failed before retrying.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#orchestration_dispatch_failed"
    },
    {
      "code": "ORCHESTRATION_HUMAN_NODE_MISMATCH",
      "http_status": 400,
      "description": "The specified node is not the active human node waiting for input.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#orchestration_human_node_mismatch"
    },
    {
      "code": "ORCHESTRATION_MAX_ITERATIONS_EXCEEDED",
      "http_status": 422,
      "description": "The orchestration run exceeded the maximum number of iterations.",
      "resolution": "The request was accepted and then could not be carried out. The failure is in the work, not the request shape — read `meta` and the trace for which step failed before retrying.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#orchestration_max_iterations_exceeded"
    },
    {
      "code": "ORCHESTRATION_NESTED_RUN_FAILED",
      "http_status": 422,
      "description": "A `loop` / `sub_orchestration` child run settled in a non-success terminal status (failed, cancelled, or expired) carrying no code of its own, so the node that started it failed too. A child that carries a code fails its parent under that code instead, so the cause reaches the run a caller reads (#1185). Matches ORCHESTRATION_DISPATCH_FAILED, the same rule for a workflow on_enter dispatch's run.",
      "resolution": "The request was accepted and then could not be carried out. The failure is in the work, not the request shape — read `meta` and the trace for which step failed before retrying.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#orchestration_nested_run_failed"
    },
    {
      "code": "ORCHESTRATION_NODE_FAILED",
      "http_status": 422,
      "description": "A node in the orchestration run failed to execute.",
      "resolution": "The request was accepted and then could not be carried out. The failure is in the work, not the request shape — read `meta` and the trace for which step failed before retrying.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#orchestration_node_failed"
    },
    {
      "code": "ORCHESTRATION_NOT_FOUND",
      "http_status": 404,
      "description": "The orchestration does not exist or is not accessible.",
      "resolution": "Check the id and the project the credential can see, then retry. Listing the collection confirms whether the resource exists.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#orchestration_not_found"
    },
    {
      "code": "ORCHESTRATION_POLL_EXHAUSTED",
      "http_status": 422,
      "description": "A poll node reached its attempt limit without its exit condition becoming true (only raised when fail_on_timeout is set).",
      "resolution": "The request was accepted and then could not be carried out. The failure is in the work, not the request shape — read `meta` and the trace for which step failed before retrying.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#orchestration_poll_exhausted"
    },
    {
      "code": "ORCHESTRATION_RUN_DEPTH_LIMIT",
      "http_status": 409,
      "description": "Starting the next `loop` / `sub_orchestration` child run would nest past the depth bound, so it was refused. This bounds a cycle no intra-graph validator can see — a graph whose `sub_orchestration` node names itself, directly or through a cycle of two graphs — which the orchestration cycle validator (intra-graph, and excluding loop nodes deliberately) cannot detect. The bound is the smaller of MAX_ORCHESTRATION_RUN_DEPTH (default 10) and the project's `max_run_depth`; the error meta names the depth reached, the limit, and which of the two set it (#1185).",
      "resolution": "Nesting is recursing: follow `parent_orchestration_run_id` up from the failed run to find the `sub_orchestration` (or `loop`) node that names a graph already in the chain, and repoint it. If the composition is legitimately this deep, raise the project bound with `PATCH /api/v1/projects/{project_id}` (`max_run_depth`) — `meta.limit_source` says whether the project or the deployment set the number that refused it.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#orchestration_run_depth_limit"
    },
    {
      "code": "ORCHESTRATION_RUN_NOT_AWAITING_INPUT",
      "http_status": 409,
      "description": "The orchestration run is not awaiting input.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#orchestration_run_not_awaiting_input"
    },
    {
      "code": "ORCHESTRATION_RUN_NOT_CANCELLABLE",
      "http_status": 409,
      "description": "The orchestration run is already in a terminal state and cannot be cancelled.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#orchestration_run_not_cancellable"
    },
    {
      "code": "ORCHESTRATION_RUN_NOT_FOUND",
      "http_status": 404,
      "description": "The orchestration run does not exist or is not accessible.",
      "resolution": "Check the id and the project the credential can see, then retry. Listing the collection confirms whether the resource exists.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#orchestration_run_not_found"
    },
    {
      "code": "ORCHESTRATION_VALIDATION_FAILED",
      "http_status": 400,
      "description": "The orchestration graph is invalid (e.g. a dangling edge, a node missing a required field, a cycle, or an input_mapping that references a state key no upstream node writes).",
      "resolution": "The orchestration graph is not runnable as declared. `meta` names the failing node or edge; `POST /api/v1/orchestrations/{orchestration_id}/validate` reports every problem at once.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#orchestration_validation_failed"
    },
    {
      "code": "OUTPUT_SCHEMA_STREAMING_UNSUPPORTED",
      "http_status": 400,
      "description": "Streaming generation does not support output_schema. Set stream to false, or remove output_schema from the agent/request.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#output_schema_streaming_unsupported"
    },
    {
      "code": "OUTPUT_SCHEMA_VALIDATION_FAILED",
      "http_status": 502,
      "description": "The model returned an object that does not satisfy the agent output_schema (or was not valid JSON at all). Upstream-caused like AI_PROVIDER_ERROR: the request was well-formed, the model output was not.",
      "resolution": "An upstream dependency failed rather than this server itself. Retry with backoff and check that dependency.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#output_schema_validation_failed"
    },
    {
      "code": "PDF_PARSE_FAILED",
      "http_status": 400,
      "description": "The uploaded file could not be parsed as a PDF. Ensure the file is a valid PDF document.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#pdf_parse_failed"
    },
    {
      "code": "PIPELINE_DEPTH_EXCEEDED",
      "http_status": 422,
      "description": "The pipeline tool exceeded the maximum nested execution depth (pipelines calling pipelines).",
      "resolution": "The request was accepted and then could not be carried out. The failure is in the work, not the request shape — read `meta` and the trace for which step failed before retrying.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#pipeline_depth_exceeded"
    },
    {
      "code": "PIPELINE_INVALID_STEP",
      "http_status": 400,
      "description": "The pipeline tool configuration is invalid (e.g. no steps, a duplicate or malformed step id, a missing tool reference, a forward reference to a later step, or a step that targets a client tool).",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#pipeline_invalid_step"
    },
    {
      "code": "PIPELINE_STEP_FAILED",
      "http_status": 422,
      "description": "A step in the pipeline tool failed to execute.",
      "resolution": "The request was accepted and then could not be carried out. The failure is in the work, not the request shape — read `meta` and the trace for which step failed before retrying.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#pipeline_step_failed"
    },
    {
      "code": "POLICY_NOT_FOUND",
      "http_status": 400,
      "description": "A referenced policy does not exist.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#policy_not_found"
    },
    {
      "code": "PROJECT_DEFAULT_ROUTE_INHERITED",
      "http_status": 409,
      "description": "A project's default_model_route_id cannot be cleared while consumers that bind neither an AI provider nor a model route inherit it — clearing it would leave them with no resolvable model. Repointing the default to another route is always allowed; the error meta reports the count and a sample of inheriting resource IDs.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#project_default_route_inherited"
    },
    {
      "code": "PROJECT_HAS_DEPENDENTS",
      "http_status": 409,
      "description": "The project has one or more dependent resources (agents, ai providers, tools, etc.) and cannot be deleted. Use force=true to delete dependents as well.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#project_has_dependents"
    },
    {
      "code": "PROMOTION_GATE_UNMET",
      "http_status": 409,
      "description": "The release's promotion_gate has no passing eval run against the canary version. Run the eval with agent_version pinned to the canary, or abort the rollout.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#promotion_gate_unmet"
    },
    {
      "code": "QUEUE_DRIVER_MISCONFIGURED",
      "http_status": 500,
      "description": "The orchestration queue driver is not configured correctly — an unknown ORCHESTRATION_QUEUE_DRIVER, or a missing required variable for the selected driver (e.g. ORCHESTRATION_QUEUE_SQS_QUEUE_URL for sqs).",
      "resolution": "Retry with backoff. If it persists, the server log carries the detail the response deliberately omits.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#queue_driver_misconfigured"
    },
    {
      "code": "QUOTA_CONFLICT",
      "http_status": 409,
      "description": "A quota with the same (project, scope, scope_ref, metric, window) already exists. The all-enforce precedence rule makes duplicates pure redundancy, so a duplicate is rejected instead of stored.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#quota_conflict"
    },
    {
      "code": "QUOTA_EXCEEDED",
      "http_status": 429,
      "description": "An enforced quota has been exceeded for the request scope. The response carries a `Retry-After` header (seconds until the window resets) and a `meta` block naming the breached quota, metric, limit, window, and reset time.",
      "resolution": "Wait until the window resets — `Retry-After` (seconds) and `meta.resets_at` both carry the time — or raise the quota with `PATCH /api/v1/quotas/{quota_id}`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#quota_exceeded"
    },
    {
      "code": "QUOTA_UNENFORCEABLE",
      "http_status": 409,
      "description": "An enforced `cost_usd` quota with `on_unpriced: \"block\"` (the default) cannot be evaluated: the current window holds a pricing blackout — several metered events, none of them priced — so the aggregate is `0` however much was actually spent. The cap refuses the generation rather than waving through spend it cannot measure. No `Retry-After` is sent — the window resetting changes nothing; configure pricing for the models in use, or set the quota's `on_unpriced` to `\"allow\"` to accept unmeasurable spend explicitly.",
      "resolution": "Add price book entries covering the models this project runs (`POST /api/v1/prices`), so the cost quota has something to aggregate. To accept unmeasurable spend instead, set `on_unpriced: \"allow\"` on the quota with `PATCH /api/v1/quotas/{quota_id}` (or switch it to `monitor` mode to stop blocking entirely).",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#quota_unenforceable"
    },
    {
      "code": "REQUEST_REJECTED",
      "http_status": 400,
      "description": "The HTTP framework rejected the request before it reached a handler — a payload over the size limit, an unsupported method, a malformed request line. The accompanying message carries the specific reason, and the response status is the one the framework chose rather than this default.",
      "resolution": "The HTTP layer rejected the request before it reached a route — method, content type, or size. The message names the reason.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#request_rejected"
    },
    {
      "code": "RESOURCE_NOT_FOUND",
      "http_status": 404,
      "description": "The requested resource does not exist or is not accessible.",
      "resolution": "Check the id, and check that the credential can see the project that owns the resource — a resource in another project is indistinguishable from one that does not exist. List the collection to confirm.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#resource_not_found"
    },
    {
      "code": "SECRET_HAS_DEPENDENTS",
      "http_status": 409,
      "description": "The secret is referenced by one or more AI providers and cannot be deleted. Use force=true to delete dependents as well.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#secret_has_dependents"
    },
    {
      "code": "SECRET_NOT_DECRYPTABLE",
      "http_status": 500,
      "description": "A stored trigger or webhook secret could not be decrypted — SECRETS_ENCRYPTION_KEY has changed since it was written. Rotating the secret replaces it; restoring the original key recovers every secret written under it.",
      "resolution": "Retry with backoff. If it persists, the server log carries the detail the response deliberately omits.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#secret_not_decryptable"
    },
    {
      "code": "SECRET_NOT_FOUND",
      "http_status": 400,
      "description": "A secret referenced by a {{secret:...}} token does not exist in this project.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#secret_not_found"
    },
    {
      "code": "SESSION_CLOSED",
      "http_status": 409,
      "description": "The session is closed and does not accept new messages or generation requests. Open a new session to continue.",
      "resolution": "The session is closed and accepts no further messages. Open a new one, or fork this one to keep its history.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#session_closed"
    },
    {
      "code": "SESSION_EXPIRED",
      "http_status": 410,
      "description": "The session has expired due to inactivity. Open a new session to continue.",
      "resolution": "Open a new session; an expired one cannot be revived. Raise the agent's session TTL if this happens sooner than the workload needs.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#session_expired"
    },
    {
      "code": "SINGLE_SESSION_CONFLICT",
      "http_status": 409,
      "description": "An open session already exists for this actor. Use the existing session or close it first.",
      "resolution": "The agent allows one open session per actor. Reuse the session named in `meta.session_id`, or close it first.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#single_session_conflict"
    },
    {
      "code": "SYSTEM_MESSAGE_NOT_ALLOWED",
      "http_status": 400,
      "description": "A `role: \"system\"` entry was supplied in `messages`. System content never travels as a message on any SOAT surface — it goes in the `instructions` field instead — the same name on every surface (a completion request, a Chat, an Agent). Mirrors the AI SDK, whose `allowSystemInMessages` defaults to false because a system entry in a caller-supplied array is a prompt-injection vector.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#system_message_not_allowed"
    },
    {
      "code": "TASK_AUTOMATION_CHAIN_LIMIT",
      "http_status": 409,
      "description": "The task has run too many machine-driven transitions back-to-back with no outside intervention, and the next one was refused. This bounds a cycle composed across modules — a workflow state dispatching work that transitions the task back into that same state — which neither the orchestration cycle validator (intra-graph) nor the workflow itself (where revisiting states is deliberate) can see. Any move by a person, a plain API key, or an approval resolution resets the chain. The ceiling is TASK_AUTOMATION_CHAIN_LIMIT (default 50) (#885).",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#task_automation_chain_limit"
    },
    {
      "code": "TASK_AUTOMATION_PROVENANCE_MISSING",
      "http_status": 500,
      "description": "An automation-caused transition was about to be persisted with no recorded cause: principal_id, generation_id, and orchestration_run_id would all be null. This is a writer bug, not a valid degraded record — the transition is rejected instead of being silently written (#792).",
      "resolution": "Retry with backoff. If it persists, the server log carries the detail the response deliberately omits.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#task_automation_provenance_missing"
    },
    {
      "code": "TASK_GUARD_REJECTED",
      "http_status": 400,
      "description": "The transition guard evaluated to false for this task.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#task_guard_rejected"
    },
    {
      "code": "TASK_NOT_FOUND",
      "http_status": 404,
      "description": "The task does not exist or is not accessible.",
      "resolution": "Check the id and the project the credential can see, then retry. Listing the collection confirms whether the resource exists.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#task_not_found"
    },
    {
      "code": "TASK_PAYLOAD_INVALID",
      "http_status": 400,
      "description": "The task payload does not satisfy the workflow's payload_schema.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#task_payload_invalid"
    },
    {
      "code": "TASK_STATE_NOT_FOUND",
      "http_status": 400,
      "description": "A task create request's `state` does not name a declared state of the workflow.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#task_state_not_found"
    },
    {
      "code": "TASK_TRANSITION_CONFLICT",
      "http_status": 409,
      "description": "A concurrent change made the requested transition invalid from the current state, or the task is already closed.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#task_transition_conflict"
    },
    {
      "code": "TASK_TRANSITION_NOT_FOUND",
      "http_status": 400,
      "description": "The named transition does not exist in the workflow.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#task_transition_not_found"
    },
    {
      "code": "TEXT_ENCODED_TOOL_CALL",
      "http_status": 502,
      "description": "The model wrote a tool invocation as plain assistant text (e.g. a ```json block containing {\"name\": \"<a bound tool>\", \"arguments\": {…}}) instead of making a structured tool call, so the tool never ran. Upstream-caused like AI_PROVIDER_ERROR: returning that text as the answer would be a silent data-integrity failure, so the generation fails instead.",
      "resolution": "An upstream dependency failed rather than this server itself. Retry with backoff and check that dependency.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#text_encoded_tool_call"
    },
    {
      "code": "TOOL_AUTH_FAILED",
      "http_status": 502,
      "description": "An http-type tool's `execute.auth` credentials could not be turned into a request credential — malformed service account JSON, an unusable private key, or a token endpoint that rejected the assertion. The error `meta` carries the token endpoint's status and body when it responded. Distinct from `TOOL_HTTP_ERROR`, which is the tool's own target rejecting the call.",
      "resolution": "An upstream dependency failed rather than this server itself. Retry with backoff and check that dependency.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#tool_auth_failed"
    },
    {
      "code": "TOOL_CALL_NOT_SUPPORTED",
      "http_status": 422,
      "description": "This tool type cannot be invoked server-side. Client tools must be executed by the calling client.",
      "resolution": "The request was accepted and then could not be carried out. The failure is in the work, not the request shape — read `meta` and the trace for which step failed before retrying.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#tool_call_not_supported"
    },
    {
      "code": "TOOL_DISPATCH_FAILED",
      "http_status": 422,
      "description": "A workflow on_enter `tool` dispatch did not return a result. The tool call was settled before it ran — blocked by a guardrail (class D or a class-B tripwire), or routed to human approval (class C), which a task dispatch cannot park on. The error `meta` carries the `tool_id` and the `outcome` that settled it. Dispatch an orchestration instead when the tool is approval-gated: its engine can park and resume.",
      "resolution": "The request was accepted and then could not be carried out. The failure is in the work, not the request shape — read `meta` and the trace for which step failed before retrying.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#tool_dispatch_failed"
    },
    {
      "code": "TOOL_EGRESS_BLOCKED",
      "http_status": 403,
      "description": "An http- or mcp-type tool's target is not publicly routable — a loopback, private, link-local (cloud metadata), CGNAT or IPv6 ULA address — and the deployment's TOOL_EGRESS_ALLOWED_HOSTS does not list it. Also returned when a hostname resolves to such an address, when a redirect leads to one, when the scheme is not http/https, or when the redirect chain is too long. The error `meta` carries `tool_url` and, when known, the offending `tool_address`.",
      "resolution": "The credential is authenticated but lacks this action, or is scoped to another project. Grant the action in an IAM policy, or use a credential that has it.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#tool_egress_blocked"
    },
    {
      "code": "TOOL_HTTP_ERROR",
      "http_status": 502,
      "description": "An http-type tool call returned a non-2xx response. The error `meta` carries the real upstream status code, response body, URL, and method.",
      "resolution": "An upstream dependency failed rather than this server itself. Retry with backoff and check that dependency.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#tool_http_error"
    },
    {
      "code": "TOOL_NOT_FOUND",
      "http_status": 400,
      "description": "A referenced tool does not exist.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#tool_not_found"
    },
    {
      "code": "TRIGGER_ACTION_NOT_ALLOWED",
      "http_status": 400,
      "description": "A trigger field is incompatible with its type: `action` is only valid for tool targets (and required for soat/mcp tools), and `cron` is required for schedule triggers and rejected otherwise.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#trigger_action_not_allowed"
    },
    {
      "code": "TRIGGER_CAUSATION_LIMIT",
      "http_status": 409,
      "description": "An event trigger refused to extend the causal chain that reached it — it is already in the chain, or the chain has run too deep.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#trigger_causation_limit"
    },
    {
      "code": "TRIGGER_CREATOR_UNAVAILABLE",
      "http_status": 409,
      "description": "The trigger creator no longer exists, so the firing identity cannot be resolved.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#trigger_creator_unavailable"
    },
    {
      "code": "TRIGGER_INPUT_INVALID",
      "http_status": 400,
      "description": "The effective input is invalid for the target (empty agent input, or an orchestration input_schema violation).",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#trigger_input_invalid"
    },
    {
      "code": "TRIGGER_NOT_ACTIVE",
      "http_status": 409,
      "description": "The trigger is inactive and cannot fire.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#trigger_not_active"
    },
    {
      "code": "TRIGGER_RECURSION_FORBIDDEN",
      "http_status": 403,
      "description": "A trigger-scoped credential cannot fire a trigger, preventing unbounded trigger→trigger loops.",
      "resolution": "The credential is authenticated but lacks this action, or is scoped to another project. Grant the action in an IAM policy, or use a credential that has it.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#trigger_recursion_forbidden"
    },
    {
      "code": "TRIGGER_TARGET_NOT_FOUND",
      "http_status": 400,
      "description": "The trigger target does not exist in the project, or its type does not match target_type.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#trigger_target_not_found"
    },
    {
      "code": "TRIGGER_TYPE_IMMUTABLE",
      "http_status": 400,
      "description": "A trigger’s type cannot be changed after creation.",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#trigger_type_immutable"
    },
    {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "description": "Authentication is required or the token is invalid.",
      "resolution": "Send `Authorization: Bearer <token>` — a user token from `POST /api/v1/users/login`, a project API key (`sk_…`), or an OAuth access token. Discovery metadata for the OAuth flow is at `/.well-known/oauth-authorization-server`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#unauthorized"
    },
    {
      "code": "UNSUPPORTED_FILE_TYPE",
      "http_status": 400,
      "description": "The referenced file has a content type that cannot be ingested. Supported types: application/pdf, text/plain, text/markdown.",
      "resolution": "The file's media type has no parser on this deployment. Convert it to a supported type, or add an ingestion rule that does.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#unsupported_file_type"
    },
    {
      "code": "UPLOAD_TOKEN_EXPIRED",
      "http_status": 410,
      "description": "The upload token has expired. Request a new one.",
      "resolution": "Request a fresh upload token; tokens are single-use and short-lived by design.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#upload_token_expired"
    },
    {
      "code": "UPLOAD_TOKEN_NOT_FOUND",
      "http_status": 404,
      "description": "The upload token does not exist.",
      "resolution": "Check the id and the project the credential can see, then retry. Listing the collection confirms whether the resource exists.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#upload_token_not_found"
    },
    {
      "code": "UPLOAD_TOKEN_USED",
      "http_status": 409,
      "description": "The upload token has already been used.",
      "resolution": "This upload token has already been redeemed. Request a new one for another upload.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#upload_token_used"
    },
    {
      "code": "VALIDATION_FAILED",
      "http_status": 400,
      "description": "The request body failed validation.",
      "resolution": "Fix the request and retry. Unknown fields are rejected outright, so compare the payload against the operation in `/openapi.json`; `meta` names the offending field when the check can identify one.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#validation_failed"
    },
    {
      "code": "WORKFLOW_HAS_OPEN_TASKS",
      "http_status": 409,
      "description": "The workflow has one or more open tasks and cannot be deleted.",
      "resolution": "The request is well-formed but the resource is not in a state that allows it. Resolve the conflicting state named in the message, then retry.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#workflow_has_open_tasks"
    },
    {
      "code": "WORKFLOW_NOT_FOUND",
      "http_status": 404,
      "description": "The workflow does not exist or is not accessible.",
      "resolution": "Check the id and the project the credential can see, then retry. Listing the collection confirms whether the resource exists.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#workflow_not_found"
    },
    {
      "code": "WORKFLOW_VALIDATION_FAILED",
      "http_status": 400,
      "description": "The workflow definition is invalid (e.g. duplicate state names, not exactly one initial state, a transition referencing an unknown state, a malformed guard, or an on_enter dispatch missing its target).",
      "resolution": "Fix the request and retry — the payload, parameters, or referenced ids are invalid. Compare the request against the operation in `/openapi.json`.",
      "docs_url": "https://soat.ttoss.dev/docs/error-codes#workflow_validation_failed"
    }
  ]
}