{ "$comment": "Generated by docs-site/scripts/generate-artifacts.mjs from scripts/data/errors.mjs, which cites the service source files each code was read from. Do not edit by hand.", "envelope": "THE ENVELOPE DEPENDS ON THE PLANE — there is no single shape across Aetherfy. Vector API (vectors.aetherfy.com, entries with surface \"vectors\"): errors are returned as {\"error\": {\"code\": \"...\", \"message\": \"...\"}}, sometimes with extra fields such as field, max, request_id, collection_name, existing_regions, size_mb or retriable. That envelope is universal on this plane: every path authors it, including the storage-engine pass-through routes, which normalise the engine's native body on the way out, so a generic handler can rely on error.code being present. Control plane (agents.aetherfy.com, entries with origin \"control-plane\"): errors are returned as {\"detail\": {\"code\": \"...\", \"message\": \"...\", ...extras}} — `detail`, not `error`. Two further differences bite clients. First, the envelope covers ROUTED errors only: a path that matches no route never reaches the control plane's error handling and gets the framework default {\"detail\": \"Not Found\"}, where detail is a plain STRING and detail.code is undefined. On a request-schema validation failure the envelope DOES hold — detail stays an object with code VALIDATION_ERROR, and the per-field errors sit in detail.violations. Second, the ENVELOPE is now the only auth difference between the planes, and this CHANGED on 2026-08-20. The auth codes are unified: MISSING_API_KEY, INVALID_API_KEY, ACCOUNT_SUSPENDED and AUTHENTICATION_ERROR mean the same condition at the same status on whichever host answers. The control plane used to spell them AUTH_REQUIRED / AUTH_INVALID_API_KEY / AUTH_ACCOUNT_SUSPENDED / AUTH_SERVICE_ERROR; those strings are no longer emitted anywhere, so a client still matching on them now matches nothing. Read detail.code on the control plane and error.code on the vector API — the shape still differs even though the string no longer does. One auth code keeps an AUTH_ prefix, AUTH_SUBSCRIPTION_INACTIVE, because the vector API has no equivalent condition to unify it with.", "retryAfterHeaderNote": "CHANGED SHAPE: retryAfterHeader was a platform-wide boolean (false) and is now an object keyed by host, because the two planes genuinely differ. Read retryAfterHeader[\"agents.aetherfy.com\"], not the field itself — as an object it is always truthy.", "retryAfterHeader": { "vectors.aetherfy.com": false, "agents.aetherfy.com": true }, "originLegend": { "$note": "origin values come from two different axes. Group by `surface` for the product area, and treat origin === \"control-plane\" as the envelope discriminator (detail.code rather than error.code). Entries with no origin are authored by the route that serves them.", "limiter": "component — the vector backend rate limiter", "normalizer": "component — the vector backend error normaliser", "control-plane": "service — agents.aetherfy.com; these use the detail.code envelope" }, "tierLegend": { "$note": "Aetherfy answers a failed request in one of two shapes, and a code belongs to one or both. TOP-LEVEL (\"detail\"): the code IS the response code — detail.code on the control plane, error.code on the vector API. VIOLATION (\"violation\"): the code is an entry inside detail.violations[], and the response's own top-level code is VALIDATION_VIOLATIONS (or, on a few routes, a specific top-level code that also names the failure). A client switching only on the top-level code never sees a violation-tier code — iterate the array. Dual-tier codes are real and enumerated: the same code can be top-level on one route and a violation entry on another, so read `tiers` rather than assuming.", "detail": "appears as the response's top-level code", "violation": "appears as an entry in detail.violations[]" }, "count": 147, "errors": [ { "code": "MISSING_API_KEY", "status": 401, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "No API key was supplied. Send `Authorization: Bearer `." }, { "code": "INVALID_API_KEY", "status": 401, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "The API key is not recognised. It may have been revoked." }, { "code": "ACCOUNT_SUSPENDED", "status": 403, "retryable": false, "surface": "platform", "tiers": [ "detail" ], "meaning": "The account is suspended for billing reasons. Settle the balance in billing settings." }, { "code": "COLLECTION_OWNERSHIP_MISMATCH", "status": 403, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "The collection belongs to another account." }, { "code": "VALIDATION_ERROR", "status": 400, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "A request field failed validation. The body names the offending `field` and, for numeric caps, its `max`." }, { "code": "INVALID_POINT_ID", "status": 400, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "A point id must be an unsigned integer up to 2^53-1, or a UUID string." }, { "code": "TOO_MANY_POINTS", "status": 400, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "An upsert carried more than 10000 points. Split the call." }, { "code": "RESERVED_FIELD", "status": 400, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "A payload key beginning `__aetherfy_` that Aetherfy never returns on a read — the replication and metering keys. `__aetherfy_agent_id` and `__aetherfy_deployment_id` are NOT among them: they are returned, may be sent back, and are ignored rather than rejected." }, { "code": "MALFORMED_JSON", "status": 400, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "The request body was not valid JSON." }, { "code": "SCHEMA_VALIDATION_FAILED", "status": 400, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "Points did not satisfy the collection payload schema under strict enforcement." }, { "code": "INVALID_ENFORCEMENT_MODE", "status": 400, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "Schema enforcement mode must be one of `off`, `warn`, `strict`." }, { "code": "INVALID_SAMPLE_SIZE", "status": 400, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "sample_size must be an integer between 100 and 10000. Shared by the schema analyze and conformance endpoints." }, { "code": "INVALID_SCAN_MODE", "status": 400, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "Schema conformance scan mode must be `sample` or `full`." }, { "code": "INVALID_MAX_EXAMPLES", "status": 400, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "Schema conformance max_examples must be an integer between 0 and 100." }, { "code": "COLLECTION_LIMIT_EXCEEDED", "status": 400, "retryable": false, "surface": "platform", "tiers": [ "detail" ], "meaning": "The account is at its plan collection limit." }, { "code": "WORKSPACE_LIMIT_EXCEEDED", "status": 400, "retryable": false, "surface": "platform", "tiers": [ "detail" ], "meaning": "The account is at its plan workspace limit." }, { "code": "INVALID_WORKSPACE_REGIONS", "status": 400, "retryable": false, "surface": "platform", "tiers": [ "detail" ], "meaning": "The requested workspace regions are invalid or exceed the plan region count." }, { "code": "NOT_FOUND", "status": 404, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "The endpoint is not part of the Aetherfy vector API surface, or the resource does not exist." }, { "code": "COLLECTION_NOT_FOUND", "status": 404, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "No such collection in this account." }, { "code": "SCHEMA_NOT_DEFINED", "status": 404, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "The collection has no payload schema set." }, { "code": "WORKSPACE_NOT_FOUND", "status": 404, "retryable": false, "surface": "platform", "tiers": [ "detail" ], "meaning": "No such workspace in this account." }, { "code": "METHOD_NOT_ALLOWED", "status": 405, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "The HTTP method is not supported on this path. Collections are created with `POST /api/v1/collections`, not a Qdrant-native `PUT`." }, { "code": "REQUEST_IDLE_TIMEOUT", "status": 408, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "A streaming upsert sent no bytes for 30 seconds and was closed." }, { "code": "COLLECTION_EXISTS_IN_OTHER_REGION", "status": 409, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "A collection of that name already exists in a different region of this account." }, { "code": "COLLECTION_NAME_TAKEN", "status": 409, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "A collection of that name already exists with a different configuration." }, { "code": "COLLECTION_IN_USE", "status": 409, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "An agent was OBSERVED reading or writing this collection in the last 35 days. The body names them in an agents array. Nothing is declared — a collection an agent created at runtime is protected the same way." }, { "code": "CLEANUP_IN_PROGRESS", "status": 409, "retryable": true, "surface": "vectors", "tiers": [ "detail" ], "meaning": "A previous delete of this collection is still finishing. Retry shortly — the body carries `retriable: true`." }, { "code": "DEPLOYMENT_IN_PROGRESS", "status": 409, "retryable": true, "surface": "agents", "tiers": [ "detail" ], "meaning": "Another deployment for this agent is already running." }, { "code": "AGENT_RUN_INELIGIBLE_STATE", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "meaning": "The agent is not in a state that can start a run." }, { "code": "SCHEMA_VERSION_MISMATCH", "status": 412, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "The `If-Match` ETag did not match the stored schema version. Re-read and retry." }, { "code": "PAYLOAD_TOO_LARGE", "status": 400, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "A single point payload exceeded the 64 KB per-point cap." }, { "code": "PAYLOAD_TOO_LARGE", "status": 413, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "An upsert request body exceeded the 500 MB wire ceiling." }, { "code": "RESPONSE_TOO_LARGE", "status": 413, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "The response would exceed 10 MB. Reduce the id count, lower `limit`, or omit vectors." }, { "code": "COLLECTION_REGIONS_EMPTY", "status": 422, "retryable": false, "surface": "platform", "tiers": [ "detail" ], "meaning": "An explicitly empty region list is not a valid placement." }, { "code": "COLLECTION_REGIONS_NOT_IN_SCOPE", "status": 422, "retryable": false, "surface": "platform", "tiers": [ "detail" ], "meaning": "The requested regions fall outside the workspace region scope." }, { "code": "STARTER_REGION_CONSISTENCY", "status": 422, "retryable": false, "surface": "platform", "tiers": [ "detail" ], "meaning": "Free and Starter plans are single-region. The account already has a home region and new resources must use it; migrate existing resources or move to a multi-region plan." }, { "code": "WORKSPACE_REGIONS_EMPTY", "status": 422, "retryable": false, "surface": "platform", "tiers": [ "detail" ], "meaning": "An explicitly empty workspace region list is not valid." }, { "code": "PLAN_LIMIT_EXCEEDED", "status": 403, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "limitValues": [ "max_agents", "max_regions", "max_memory_mb", "memory_mb", "max_idle_timeout_minutes", "allows_always_on", "dockerfile_runtime_allowed" ], "meaning": "The request exceeds a plan limit (agents, memory, regions, always-on, idle timeout, or custom Dockerfile builds). `detail.limit` names which one: max_agents, max_regions, max_memory_mb, memory_mb, max_idle_timeout_minutes, allows_always_on or dockerfile_runtime_allowed. It is present on every plan-cap rejection. Note memory has two: max_memory_mb means the value exceeds your plan and needs an upgrade, memory_mb means the value is not one of the supported sizes at all and needs changing on any plan." }, { "code": "DEPLOY_REGIONS_NOT_IN_SCOPE", "status": 403, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "meaning": "The deployment regions fall outside the agent workspace region scope." }, { "code": "RUNTIME_IMMUTABLE", "status": 422, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "meaning": "An agent runtime is fixed at creation. Delete and recreate the agent to change it." }, { "code": "AGENT_NOT_DEPLOYED", "status": 422, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "meaning": "The agent has no successful deployment yet. Deploy it first." }, { "code": "AGENT_SCHEDULE_NOT_SET", "status": 422, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "meaning": "The agent has no schedule, so there is nothing to pause or resume." }, { "code": "OVERAGE_CONFIRM_REQUIRED", "status": 402, "retryable": false, "surface": "platform", "tiers": [ "detail" ], "meaning": "The deployment would add usage beyond the plan allowance. Confirm to proceed; the body names the added monthly amount." }, { "code": "SOFT_CAP_EXCEEDED", "status": 403, "retryable": false, "surface": "platform", "tiers": [ "detail" ], "meaning": "The account reached its usage limit, so cost-increasing actions are frozen. Existing agents keep running. Raise the spend limit or upgrade." }, { "code": "DUNNING_FROZEN", "status": 403, "retryable": false, "surface": "platform", "tiers": [ "detail" ], "meaning": "A payment issue is on file, so growth is paused. Existing agents keep running; this clears automatically once payment succeeds." }, { "code": "RATE_LIMIT_EXCEEDED", "status": 429, "retryable": true, "surface": "vectors", "tiers": [ "detail" ], "origin": "limiter", "meaning": "The per-minute request allowance for the plan was exceeded. The window is a fixed 60-second bucket. No `Retry-After` header is sent — back off on your own schedule. The SDKs expose a retry_after / retryAfter attribute on RateLimitExceededError, but since no header is sent there is nothing to populate it from; do not branch on it." }, { "code": "STORAGE_LIMIT_EXCEEDED", "status": 429, "retryable": false, "surface": "platform", "tiers": [ "detail" ], "meaning": "The account is at its storage cap. Writes are refused; reads are never blocked. Free space or upgrade. Storage counts every replica." }, { "code": "INTERNAL_ERROR", "status": 500, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "meaning": "An unexpected server error. Retrying an identical write is not automatically safe." }, { "code": "PROXY_ERROR", "status": 502, "retryable": true, "surface": "vectors", "tiers": [ "detail" ], "meaning": "The request could not be forwarded to the storage engine. Transient." }, { "code": "SERVICE_UNAVAILABLE", "status": 503, "retryable": true, "surface": "vectors", "tiers": [ "detail" ], "meaning": "The storage engine is unreachable or a circuit breaker is open. Transient." }, { "code": "SERVICE_UNAVAILABLE", "status": 503, "retryable": true, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "A service the request depended on was unreachable, most often the plan lookup that checks your limits. Nothing was written. Transient." }, { "code": "GATEWAY_TIMEOUT", "status": 504, "retryable": true, "surface": "vectors", "tiers": [ "detail" ], "meaning": "The storage engine did not respond within 30 seconds. Transient." }, { "code": "BAD_REQUEST", "status": 400, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "origin": "normalizer", "meaning": "The storage engine rejected the request and supplied no code of its own. Read the message." }, { "code": "UNAUTHORIZED", "status": 401, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "origin": "normalizer", "meaning": "An upstream component refused the credentials without naming a code. Distinct from MISSING_API_KEY / INVALID_API_KEY, which Aetherfy authors when it rejects the key itself." }, { "code": "FORBIDDEN", "status": 403, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "origin": "normalizer", "meaning": "An upstream component denied the request without naming a code." }, { "code": "CONFLICT", "status": 409, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "origin": "normalizer", "meaning": "The upstream reported a conflicting state without naming a code. The named 409s above (COLLECTION_NAME_TAKEN, COLLECTION_IN_USE, CLEANUP_IN_PROGRESS) are more specific." }, { "code": "PRECONDITION_FAILED", "status": 412, "retryable": false, "surface": "vectors", "tiers": [ "detail" ], "origin": "normalizer", "meaning": "A precondition failed upstream without a named code — typically an ETag mismatch. The named form is SCHEMA_VERSION_MISMATCH." }, { "code": "RATE_LIMITED", "status": 429, "retryable": true, "surface": "vectors", "tiers": [ "detail" ], "origin": "normalizer", "meaning": "A 429 arrived from upstream carrying no code of its own. NOT the same as RATE_LIMIT_EXCEEDED, which is Aetherfy's own per-minute limiter refusing the request — check the code, not just the status." }, { "code": "UPSTREAM_ERROR", "status": 502, "retryable": true, "surface": "vectors", "tiers": [ "detail" ], "origin": "normalizer", "meaning": "The catch-all: an upstream failure whose status is none of the mapped ones (most often 500, 502, 503 or 504) and which carried no code. The status is the retry signal here, not the code." }, { "code": "MISSING_API_KEY", "status": 401, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "unificationNote": "RENAMED 2026-08-20 from AUTH_REQUIRED. The control plane now uses the vector plane's spelling for this condition; AUTH_REQUIRED is no longer emitted anywhere.", "meaning": "No Authorization header. The same code and status the vector API answers, though only the control plane adds WWW-Authenticate: Bearer." }, { "code": "INVALID_API_KEY", "status": 401, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "unificationNote": "RENAMED 2026-08-20 from AUTH_INVALID_API_KEY. The control plane now uses the vector plane's spelling for this condition; AUTH_INVALID_API_KEY is no longer emitted anywhere.", "meaning": "The API key does not resolve — it may have been revoked. Same code and status as the vector API." }, { "code": "ACCOUNT_SUSPENDED", "status": 403, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "unificationNote": "RENAMED 2026-08-20 from AUTH_ACCOUNT_SUSPENDED. The control plane now uses the vector plane's spelling for this condition; AUTH_ACCOUNT_SUSPENDED is no longer emitted anywhere.", "meaning": "The account is suspended for unpaid bills. A suspension refuses both products under this one code." }, { "code": "AUTHENTICATION_ERROR", "status": 500, "retryable": true, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "unificationNote": "RENAMED 2026-08-20 from AUTH_SERVICE_ERROR. The control plane now uses the vector plane's spelling for this condition; AUTH_SERVICE_ERROR is no longer emitted anywhere.", "meaning": "Authentication itself failed rather than rejecting the key. Retry." }, { "code": "AUTHENTICATION_ERROR", "status": 500, "retryable": true, "surface": "vectors", "tiers": [ "detail" ], "meaning": "Authentication itself failed rather than rejecting the key. Retry." }, { "code": "AUTH_SUBSCRIPTION_INACTIVE", "status": 403, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The subscription is not active, trialing or past due. The body carries subscription_status. Control-plane only — the vector API has no equivalent, which is why this one keeps the AUTH_ prefix." }, { "code": "RESOURCE_BUSY", "status": 503, "retryable": true, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "A background worker held a row lock longer than the request-path bound, so the request was refused rather than left hanging. Always safe to retry." }, { "code": "VALIDATION_VIOLATIONS", "status": 400, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "Several semantic rules failed at once. Read the `violations` array — each entry carries its own code — rather than the top-level message." }, { "code": "USER_NOT_FOUND", "status": 404, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The authenticated user has no account record on this plane." }, { "code": "AGENT_NOT_FOUND", "status": 404, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "No agent with that id or name. The same answer is given for an agent belonging to another account — existence is not distinguished from ownership." }, { "code": "AGENT_NAME_TAKEN", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "Another agent on this account already has that name. Names are unique per account." }, { "code": "AGENT_ALREADY_PAUSED", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "Stop was called on an agent already paused." }, { "code": "AGENT_NOT_PAUSED", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "Start was called on an agent that was not paused." }, { "code": "AGENT_ALREADY_ARCHIVED", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The agent is archived. Restore it before operating on it." }, { "code": "AGENT_NOT_ARCHIVED", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "Restore was called on an agent that was not archived." }, { "code": "AGENT_NOT_PAUSEABLE_SYSTEM_STATE", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "Aetherfy owns the agent’s current state (for example usage_paused), so a user pause does not apply." }, { "code": "AGENT_NOT_ARCHIVABLE_SYSTEM_STATE", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "Aetherfy owns the agent’s current state, so it cannot be archived right now." }, { "code": "AGENT_HAS_PENDING_DEPLOYMENTS", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "A build is still running. Carries pending_deployments. Wait for active or failed." }, { "code": "AGENT_HAS_WORKER_DEPENDENTS", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "Another agent lists this one in spawn.workers. Carries dependents — remove it there first." }, { "code": "AGENT_NO_MACHINES", "status": 400, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "Start was called on an agent with no machines. Deploy it first." }, { "code": "AGENT_OPERATION_IN_PROGRESS", "status": 409, "retryable": true, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "A worker holds this agent mid-transaction. Transient by construction — the ONLY agent 409 that is safe to retry blindly; the others describe a state you must change first." }, { "code": "AGENT_PAUSE_FAILED", "status": 503, "retryable": true, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The machine host was unreachable while pausing. The agent’s status is unchanged, so retrying is safe." }, { "code": "AGENT_RESUME_FAILED", "status": 503, "retryable": true, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The machine host was unreachable while resuming. The agent is still paused." }, { "code": "AGENT_TOGGLE_RATE_LIMITED", "status": 429, "retryable": true, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "Always-on was toggled too rapidly on this agent." }, { "code": "AGENT_DEPLOYMENT_OUTSIDE_NEW_WORKSPACE_SCOPE", "status": 400, "retryable": false, "surface": "agents", "tiers": [ "detail", "violation" ], "origin": "control-plane", "meaning": "Moving the agent would leave its live deployment outside the target workspace’s region set. Carries a violations array with the deployment version, its regions and the cap." }, { "code": "DEPLOYMENT_NOT_FOUND", "status": 404, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "No deployment with that id or version for this agent." }, { "code": "DEPLOYMENT_ACCESS_DENIED", "status": 403, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The deployment’s agent belongs to another account." }, { "code": "DEPLOYMENT_ARCHIVE_TOO_LARGE", "status": 413, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The uploaded code archive exceeded the size cap." }, { "code": "RUN_PAYLOAD_TOO_LARGE", "status": 413, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The run payload (spawn or manual run) is over the inline cap. Write large data to a collection and pass its id." }, { "code": "DEPLOYMENT_CONFIG_PARSE_ERROR", "status": 422, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "aetherfy.yaml in the archive root is malformed or invalid." }, { "code": "DEPLOYMENT_UPLOAD_FAILED", "status": 500, "retryable": true, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "Aetherfy could not store the uploaded archive. Retry." }, { "code": "DEPLOYMENT_ROLLBACK_TARGET_INVALID", "status": 422, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "That version cannot be rolled back to: its image is no longer available and its stored code archive is gone too. A version with either one can be rolled back to." }, { "code": "DEPLOYMENT_REDEPLOY_SOURCE_UNAVAILABLE", "status": 422, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "That version cannot be rebuilt — its stored code archive is gone. Archives are kept for the 10 most recent successful deployments, and deleted when a build fails." }, { "code": "DEPLOYMENT_TERMINAL_CANNOT_CANCEL", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The deployment already reached a terminal state, so there is nothing to cancel." }, { "code": "DEPLOYMENT_WAIT_TIMEOUT_INVALID", "status": 422, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "timeout_seconds on the deployment wait route was outside 1 to 60. The request is held open, so anything longer is cut by the network in front of the API — wait again instead." }, { "code": "DEPLOYMENT_NOT_EPHEMERAL", "status": 404, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "A payload was requested for a normal deployment. Only scheduled, manual and spawned runs carry one." }, { "code": "AGENT_PAUSED_CANNOT_DEPLOY", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The agent is paused. Start it before deploying." }, { "code": "AGENT_PAUSED_CANNOT_ROLLBACK", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The agent is paused. Start it before rolling back." }, { "code": "AGENT_PAUSED_CANNOT_REDEPLOY", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The agent is paused. Start it before redeploying." }, { "code": "WORKER_NOT_FOUND", "status": 404, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "A name listed in spawn.workers does not resolve to an agent on this account." }, { "code": "AGENT_RUNS_INVALID_TRIGGER_SOURCE", "status": 422, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "trigger_source must be cron or manual. Carries allowed. Spawned runs are not addressable in run history." }, { "code": "AGENT_RUNS_INVALID_BEFORE", "status": 422, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The `before` pagination cursor was not an ISO-8601 timestamp." }, { "code": "AGENT_LOGS_INVALID_SINCE", "status": 400, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The `since` window was not N followed by s, m, h or d — for example 30m or 2h." }, { "code": "AGENT_LOGS_INVALID_FILTER", "status": 422, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "level or stream was not one of the accepted values. Carries the allowed set." }, { "code": "AGENT_LOGS_INVALID_DEPLOYMENT_ID", "status": 422, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "deployment_id was not a valid UUID." }, { "code": "AGENT_NOT_SPAWN_ENABLED", "status": 403, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The parent agent does not have spawn_enabled set." }, { "code": "AGENT_WORKER_NOT_ALLOWED", "status": 403, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The child is not listed in the parent’s allowed_workers." }, { "code": "AGENT_SPAWN_DEPTH_INVALID", "status": 400, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The spawn chain would exceed the maximum depth." }, { "code": "AGENT_CHILD_NOT_DEPLOYED", "status": 400, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The child agent has never deployed, so there is no image to start." }, { "code": "AGENT_PARENT_NO_DEPLOYMENT", "status": 400, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The parent agent has never deployed." }, { "code": "AGENT_PARENT_PAUSED", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The parent agent is paused. Start it first." }, { "code": "AGENT_WORKER_PAUSED", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The child agent is paused. Start it first." }, { "code": "AGENT_PARENT_NOT_SPAWNABLE", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The parent agent’s current state does not allow spawning." }, { "code": "AGENT_RUN_CONCURRENCY_LIMIT_EXCEEDED", "status": 429, "retryable": true, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The cap your plan sets on task runs in flight across the whole account, counting every trigger — spawned, manual and scheduled alike — and the only limit on runs of a busy agent, which otherwise get a machine of their own. A spawn or a manual run is refused with it; a scheduled occurrence is recorded skipped with it as its reason. `detail.limit` reads `max_in_flight_runs`, `detail.max_in_flight_runs` is the cap and `detail.in_flight_count` is where you are against it; the per-plan numbers are on /platform/limits. Wait for some runs to finish — retrying immediately will not help, and nothing was queued. NOT the same as AGENT_SPAWN_RATE_LIMITED." }, { "code": "AGENT_SERVICE_NOT_RUNNING", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "A spawn of a `type: service` agent that has no running machine in any region to take the run. `detail.regions` lists the regions its live release is in, and the message names them. Start the service or redeploy it; a spawn never deploys a service." }, { "code": "AGENT_SPAWN_RATE_LIMITED", "status": 503, "retryable": true, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "Another deploy of the same agent held its version lock too long, so this spawn could not take it. Not a collision — the allocation is serialised. Retry; if it keeps happening, a deploy is stuck. Distinct from the 429 concurrency cap." }, { "code": "SECRET_NOT_FOUND", "status": 404, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "No secret with that key on this agent or workspace." }, { "code": "SECRET_VALIDATION_ERROR", "status": 422, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The secret key or value was rejected. The message names the reason." }, { "code": "SECRET_INTERNAL_ERROR", "status": 500, "retryable": true, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "Re-encryption failed during a rotate. The stored secret is unchanged." }, { "code": "WORKSPACE_NAME_TAKEN", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "Another workspace on this account already has that name." }, { "code": "WORKSPACE_NAME_IMMUTABLE", "status": 400, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "A workspace name cannot change. Any `name` in the body must equal the one in the URL." }, { "code": "WORKSPACE_HAS_AGENTS", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The workspace still holds agents. Move or delete them first." }, { "code": "WORKSPACE_HAS_COLLECTIONS", "status": 409, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The workspace still holds collections. Move or delete them first." }, { "code": "REGION_OP_IN_FLIGHT", "status": 409, "retryable": true, "surface": "agents", "tiers": [ "detail", "violation" ], "origin": "control-plane", "meaning": "A region change is already running for this scope. Wait for the operation to finish, then retry." }, { "code": "COLLECTION_MOVE_IN_FLIGHT", "status": 409, "retryable": true, "surface": "agents", "tiers": [ "detail", "violation" ], "origin": "control-plane", "meaning": "A move is already running for this collection. Poll the operation, then retry." }, { "code": "WORKSPACE_NARROW_BLOCKED_BY_RESOURCES", "status": 422, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "Narrowing the workspace’s region set would strand resources that still use a region being removed. Carries regions_to_remove plus agent_conflicts and collection_conflicts, each naming the resource and the regions it holds. Re-deploy the listed agents and update the listed collections’ regions, then retry." }, { "code": "COLLECTION_REGIONS_WORKSPACE_COMBINED", "status": 400, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "workspace_id and regions were sent together. Send one: the workspace already implies a placement, and the two could disagree." }, { "code": "TARGET_WORKSPACE_NOT_FOUND", "status": 404, "retryable": false, "surface": "agents", "tiers": [ "violation" ], "origin": "control-plane", "tierNote": "RE-TIERED 2026-08-19. Previously catalogued as a top-level code; it is only ever an entry inside detail.violations[], never detail.code itself. A client switching on detail.code will never see it — iterate the violations array.", "meaning": "The workspace named as a move target does not exist on this account." }, { "code": "TARGET_WORKSPACE_HAS_NO_REGIONS", "status": 422, "retryable": false, "surface": "agents", "tiers": [ "violation" ], "origin": "control-plane", "tierNote": "RE-TIERED 2026-08-19. Previously catalogued as a top-level code; it is only ever an entry inside detail.violations[], never detail.code itself. A client switching on detail.code will never see it — iterate the violations array.", "meaning": "The target workspace has no region set for the collection to inherit." }, { "code": "COLLECTION_MOVE_ENQUEUE_FAILED", "status": 500, "retryable": true, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The move could not be queued. Retry." }, { "code": "OPERATION_NOT_FOUND", "status": 404, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "No operation with that id, or it belongs to another account." }, { "code": "INVALID_REGION", "status": 400, "retryable": false, "surface": "agents", "tiers": [ "detail", "violation" ], "origin": "control-plane", "tierNote": "DUAL-TIER, and it matters which route you called. PATCH /api/v1/users/me/home-region raises it as a top-level detail.code with 400. PATCH /api/v1/workspaces/{workspace}/regions emits it as an entry inside detail.violations[], under the top-level code VALIDATION_VIOLATIONS. Handle both, or branch on the route.", "meaning": "Not a region Aetherfy runs in." }, { "code": "PLAN_REGION_LIMIT", "status": 400, "retryable": false, "surface": "agents", "tiers": [ "violation" ], "origin": "control-plane", "meaning": "The requested region count exceeds the plan maximum for this scope. The entry names the plan limit and what was requested." }, { "code": "REGION_UNAVAILABLE", "status": 400, "retryable": false, "surface": "agents", "tiers": [ "violation" ], "origin": "control-plane", "meaning": "The region is temporarily closed to new placements. Retry later — this one is transient despite the 400." }, { "code": "COMPONENT_NOT_READY", "status": 400, "retryable": true, "surface": "agents", "tiers": [ "violation" ], "origin": "control-plane", "meaning": "A collection or agent in the workspace is mid-transition and cannot be moved yet. The entry names it and its state. Wait for a stable state and retry." }, { "code": "AGENT_REGION_STRANDED", "status": 400, "retryable": false, "surface": "agents", "tiers": [ "violation" ], "origin": "control-plane", "meaning": "An agent has a live deployment in a region the change would remove, which would strand it. The entry lists deployment_regions, target_regions and stranded_regions. Redeploy the agent narrower, or widen the target set." }, { "code": "HOME_REGION_NOT_APPLICABLE", "status": 400, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The plan is multi-region, so there is no account-level home region to set — placement is per resource." }, { "code": "GITHUB_NOT_CONNECTED", "status": 422, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "No GitHub account is connected. Connect it before linking an agent to a repository." }, { "code": "GITHUB_REPO_NOT_FOUND", "status": 404, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The repository is not visible to the GitHub App installation." }, { "code": "GITHUB_API_ERROR", "status": 503, "retryable": true, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "GitHub was unreachable or returned an error. Retry." }, { "code": "GITHUB_WEBHOOK_CREATE_FAILED", "status": 422, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "GitHub rejected the webhook creation — most often one already exists on the repository. Retrying the same request fails the same way." }, { "code": "GITHUB_PERSISTENCE_FAILED", "status": 500, "retryable": true, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The repository link could not be stored." }, { "code": "GITHUB_APP_NOT_CONFIGURED", "status": 501, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "The GitHub integration is not available in this environment." }, { "code": "GITHUB_INSTALLATION_NOT_FOUND", "status": 404, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "This account holds no GitHub App installation with that id. Read the ids from GET /api/v1/auth/github/status." }, { "code": "GITHUB_DELIVERY_NOT_RECORDED", "status": 500, "retryable": true, "surface": "agents", "tiers": [ "detail" ], "origin": "control-plane", "meaning": "A verified push delivery could not be recorded, so it was refused rather than accepted and possibly lost. Redeliver it from the repository webhook settings." }, { "code": "AGENT_NOT_FOUND", "status": 404, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "edge", "meaning": "The hostname is not an Aetherfy agent address. Nothing was contacted." }, { "code": "AGENT_NOT_REACHABLE", "status": 404, "retryable": false, "surface": "agents", "tiers": [ "detail" ], "origin": "edge", "meaning": "A well-formed agent address where nothing identified itself as a running agent. The control plane is authoritative for the agent state; the edge reports only what answered." }, { "code": "AGENT_UPSTREAM_FAILURE", "status": 502, "retryable": true, "surface": "agents", "tiers": [ "detail" ], "origin": "edge", "meaning": "A gateway in front of the agent answered before the agent did, so no agent response was produced. The upstream status is preserved (502 or 504) because it carries the retry signal. The edge reports what answered and does not diagnose a cause." } ] }