{"errors":[{"code":"VALIDATION","httpStatus":400,"phase":"api","summary":"The request body or parameters are invalid.","remediation":["Read error.details for the failing fields and resend a corrected request."],"retry":"after_fix"},{"code":"UNAUTHORIZED","httpStatus":401,"phase":"api","summary":"Missing, invalid or expired session token.","remediation":["Sign in again: POST /v1/auth/challenge, sign the message with your wallet, POST /v1/auth/verify."],"retry":"after_fix"},{"code":"AUTH_INVALID_SIGNATURE","httpStatus":401,"phase":"api","summary":"The signature does not match the address in the challenge.","remediation":["Sign the exact message returned by /v1/auth/challenge with the same wallet, using personal_sign (EIP-191)."],"retry":"after_fix"},{"code":"AUTH_NONCE_INVALID","httpStatus":401,"phase":"api","summary":"The challenge nonce is unknown, already used or expired.","remediation":["Request a fresh challenge and sign it within 5 minutes. Each nonce works once."],"retry":"after_fix"},{"code":"AUTH_CODE_INVALID","httpStatus":401,"phase":"api","summary":"The email sign-in code or link is wrong, used or expired.","remediation":["Check the code in the most recent email, or request a new one with POST /v1/auth/email/start."],"retry":"after_fix"},{"code":"FORBIDDEN","httpStatus":403,"phase":"api","summary":"Your wallet is not allowed to do this on this project.","remediation":["Ask the project owner to add your wallet as a member, or use the owner wallet."],"retry":"no"},{"code":"NOT_FOUND","httpStatus":404,"phase":"api","summary":"The resource does not exist or you cannot see it.","remediation":["Check the id. List resources with GET /v1/projects/:id."],"retry":"no"},{"code":"CONFLICT","httpStatus":409,"phase":"api","summary":"The resource is in a state that does not allow this action.","remediation":["Read the current state with a GET and retry only if the action is still valid."],"retry":"after_fix"},{"code":"DOMAIN_TAKEN","httpStatus":409,"phase":"api","summary":"That domain is already attached to a service.","remediation":["Remove it from the other service first, or use a different hostname."],"retry":"no"},{"code":"DOMAIN_NOT_VERIFIED","httpStatus":409,"phase":"api","summary":"The DNS records for this domain aren't in place yet.","remediation":["Add the records listed in error.details.records at your DNS provider.","DNS can take a few minutes to update. Then verify again."],"retry":"after_fix"},{"code":"RATE_LIMITED","httpStatus":429,"phase":"api","summary":"Too many requests: for this project, this key or this address.","remediation":["Wait for the period in error.details.retryAfterSeconds before retrying. Do not loop."],"retry":"yes"},{"code":"APPROVAL_REQUIRED","httpStatus":403,"phase":"api","summary":"This project needs a person to approve this action first.","remediation":["Tell the user what you want to do and that it's waiting for approval at error.details.approveUrl.","Poll GET /v1/approvals/:id (error.details.approvalId) until status is approved or denied. Don't resend before then.","Once approved, resend the exact same request with the header X-CLI-Approval: <approvalId>. Each approval works once."],"retry":"after_approval"},{"code":"APPROVAL_INVALID","httpStatus":409,"phase":"api","summary":"The approval in X-CLI-Approval doesn't match this request, was denied, used or has expired.","remediation":["Check GET /v1/approvals/:id. An approval covers one exact request (same route and body) by the same agent.","If it expired or was used, resend the request without the header to ask again."],"retry":"after_fix"},{"code":"STEP_UP_REQUIRED","httpStatus":403,"phase":"api","summary":"This action needs the person to confirm it's them (2FA or passkey) in the last 10 minutes.","remediation":["Agents: ask the user to approve this in the dashboard. Sensitive actions by people with 2FA need a fresh second factor.","People: POST /v1/auth/step-up with a 2FA code, a recovery code or a passkey response, then resend the request."],"retry":"after_step_up"},{"code":"SMOKE_TEST_FAILED","httpStatus":409,"phase":"runtime","summary":"The new version started but failed one of the service's smoke tests, so it never took traffic.","remediation":["error.detail.evidence names the request and what came back. Reproduce it against a preview or workspace.","Fix the app (or the test, if the expectation changed) and deploy again. The current version kept serving."],"retry":"after_fix"},{"code":"RELEASE_COMMAND_FAILED","httpStatus":409,"phase":"runtime","summary":"The release command (usually migrations) exited with an error, so the new version wasn't started.","remediation":["error.detail.evidence has the last lines of its output. Rehearse it on a copy of the database: POST /v1/services/:id/rehearse.","Fix the command or the migration and deploy again. The current version kept serving."],"retry":"after_fix"},{"code":"SIGNER_POLICY","httpStatus":403,"phase":"api","summary":"The managed signer's policy doesn't allow this transaction.","remediation":["error.message says which rule (chain, contract, function, value per transaction or per day, rate). Nothing was signed.","If the transaction is right, ask a project admin to change the signer's policy: PATCH /v1/signers/:id."],"retry":"after_fix"},{"code":"CANARY_FAILED","httpStatus":409,"phase":"runtime","summary":"The new version did worse than the one serving traffic while it was tried on a share of requests, so it was rolled back.","remediation":["error.details compares the canary's error rate and p95 latency with the stable version's. Check the runtime logs of this deploy for the failing requests.","Fix the cause and deploy again; the stable version kept serving the whole time."],"retry":"after_fix"},{"code":"EMAIL_DOMAIN_UNVERIFIED","httpStatus":403,"phase":"api","summary":"The from address isn't on one of this project's verified sending domains.","remediation":["Add the domain (POST /v1/projects/:id/email/domains), set the DNS records it lists (CLI writes them itself for domains bought through CLI), then verify it (POST /v1/projects/:id/email/domains/:domainId/verify).","Send from an address on that domain."],"retry":"after_fix"},{"code":"STATIC_PUBLISH_FAILED","httpStatus":409,"phase":"build","summary":"The build worked, but CLI couldn't publish its files as a static site.","remediation":["error.detail.summary says why: usually the output folder is wrong or has no index.html.","Set staticSite.outputDir to the folder your build writes (dist, build, out, public) with PUT /v1/services/:id/static-site, then deploy again. The previous version kept serving."],"retry":"after_fix"},{"code":"EDGE_BLOCKED","httpStatus":403,"phase":"api","summary":"The app's edge rules blocked this request.","remediation":["The app's owner set rules for who may reach it (GET /v1/services/:id/edge). Ask them if you should have access."],"retry":"no"},{"code":"AI_CAP_REACHED","httpStatus":402,"phase":"api","summary":"This AI call would take the project's AI spending past its monthly cap.","remediation":["error.details has the cap, what's been spent this month and what the call could cost.","A project admin can raise or remove the cap (PUT /v1/projects/:id/ai/cap), or wait for next month. Smaller max_tokens lowers the worst case."],"retry":"after_fix"},{"code":"SHADOW_NEEDS_LIVE","httpStatus":409,"phase":"api","summary":"Shadow traffic copies requests from the live version, and this service has no live version.","remediation":["Deploy normally first (POST /v1/services/:id/deploys); once it's live, try the next version in its shadow."],"retry":"after_fix"},{"code":"SHADOW_FAILED","httpStatus":409,"phase":"runtime","summary":"The version tried in the shadow didn't start for real traffic when promoted.","remediation":["The live version kept serving. Check this deploy's runtime logs, fix the cause and try again."],"retry":"after_fix"},{"code":"OPERATOR_APPROVAL_REQUIRED","httpStatus":403,"phase":"api","summary":"This operator action needs a second operator's approval (the two-person rule).","remediation":["Ask another operator who covers this area to approve it on the Operations page (error.details.approvalId).","Then send the same request again with the header X-CLI-Operator-Approval: <approvalId>. It works once, within an hour."],"retry":"after_approval"},{"code":"PAUSED_BY_OPERATOR","httpStatus":503,"phase":"api","summary":"CLI's operators have paused this for everyone while they deal with a security problem.","remediation":["Nothing is wrong with your project. Running apps keep running.","Try again later; https://clicloud.app/status says when it's back."],"retry":"yes"},{"code":"SUSPENDED_BY_OPERATOR","httpStatus":403,"phase":"api","summary":"This project is suspended by the CLI operators.","remediation":["GET /v1/projects/:id/abuse shows why. An admin can appeal: POST /v1/abuse/:id/appeal with a message.","Nothing can be deployed until the suspension is lifted."],"retry":"no"},{"code":"IDENTITY_REQUIRED","httpStatus":403,"phase":"api","summary":"This withdrawal takes the project past the amount that needs a verified identity.","remediation":["Only the person withdrawing can do this: they start a check with POST /v1/me/identity and open the returned url (Stripe asks for a document and a selfie).","Agents: tell the user; never try to verify for them. Once verified, withdraw again."],"retry":"after_fix"},{"code":"PLACEMENT_REQUIRED","httpStatus":409,"phase":"api","summary":"This project keeps everything on its own servers, and this would run on CLI's machines.","remediation":["Place the service on one of the project's servers: error.details.fix has the request (PATCH /v1/services/:id {\"serverId\"}).","Sandboxes always run on CLI's machines; a person can turn off own-servers-only in placement (PUT /v1/projects/:id/placement) if that's acceptable."],"retry":"no"},{"code":"GPU_UNAVAILABLE","httpStatus":409,"phase":"api","summary":"No server has enough free GPUs of that kind right now.","remediation":["error.details.capacity lists every server's GPUs and how many are free. Ask for fewer, another kind, or try again later.","A project can add its own GPU server: POST /v1/projects/:id/servers with gpus."],"retry":"after_fix"},{"code":"UPSTREAM_FAILED","httpStatus":502,"phase":"api","summary":"Something CLI depends on for this action (a database, a secrets manager, a chain) refused or failed.","remediation":["error.message says what answered and how. Nothing was changed.","Fix the cause it names (a token, a permission) and try again."],"retry":"after_fix"},{"code":"STREAM_EMPTY","httpStatus":402,"phase":"api","summary":"The payment stream doesn't have enough left for this request, or is closed.","remediation":["Top it up (POST /v1/streams/:id/topup) or open a new one (POST /v1/services/:id/streams)."],"retry":"after_topup"},{"code":"BUDGET_EXCEEDED","httpStatus":402,"phase":"api","summary":"The project has used its monthly budget, which is set to stop spending.","remediation":["Tell the user. They can raise or remove the budget (PUT /v1/projects/:id/budget) or wait for the next month (error.details.resetsAt).","GET /v1/projects/:id/forecast shows what was spent and how fast."],"retry":"after_fix"},{"code":"ACCESS_PASSWORD_REQUIRED","httpStatus":403,"phase":"api","summary":"This CLI server is in testing: enter the team password to use it.","remediation":["Open the dashboard and enter the team password, or POST /v1/me/access with {\"password\"}.","Ask the CLI team for the password."],"retry":"after_fix"},{"code":"AGENT_PAUSED","httpStatus":423,"phase":"api","summary":"A person paused this agent, so it can't make changes right now.","remediation":["Stop and tell the user: they paused you in the dashboard (Agents).","Reads still work. Wait for them to resume you before retrying changes."],"retry":"after_fix"},{"code":"ACCESS_PASSWORD_WRONG","httpStatus":403,"phase":"api","summary":"That isn't the team password.","remediation":["Check the password with the CLI team and try again."],"retry":"after_fix"},{"code":"CSRF_INVALID","httpStatus":403,"phase":"api","summary":"A browser request signed in with a cookie didn't carry the matching X-CLI-CSRF header.","remediation":["Send the value of the cli_csrf cookie in the X-CLI-CSRF header on every request that changes something.","API clients should use a bearer token instead of cookies."],"retry":"after_fix"},{"code":"MFA_REQUIRED","httpStatus":403,"phase":"api","summary":"This needs a person with a second factor (an authenticator app or a passkey) set up.","remediation":["Tell the user: they set one up on their account page, then try again. The project (or the server, for operators) requires it."],"retry":"no"},{"code":"MFA_CODE_INVALID","httpStatus":401,"phase":"api","summary":"That second-factor code or passkey didn't check out.","remediation":["Use the current 6-digit code from the authenticator app, a recovery code, or try the passkey again."],"retry":"after_fix"},{"code":"MFA_LOCKED","httpStatus":429,"phase":"api","summary":"Too many wrong second-factor attempts.","remediation":["Wait 15 minutes and try again."],"retry":"yes"},{"code":"SECRETS_IN_UPLOAD","httpStatus":422,"phase":"api","summary":"The uploaded code contains secrets (an .env file, a private key or a live API key).","remediation":["error.details.findings lists each file and line. Move the values into the service's variables (PUT /v1/services/:id/env) and remove them from the code.","Add files like .env to .gitignore or .cliignore so cli up skips them.","If a finding is a false alarm, resend with ?allowSecrets=true (ask the user first)."],"retry":"after_fix"},{"code":"FEATURE_DISABLED","httpStatus":501,"phase":"api","summary":"This feature is not configured on this CLI server.","remediation":["Use another option (for example x402 instead of card), or ask the operator to enable it."],"retry":"no"},{"code":"GITHUB_NOT_LINKED","httpStatus":409,"phase":"api","summary":"This account has no linked GitHub account, or its GitHub authorization expired.","remediation":["Link GitHub: POST /v1/auth/github/link and open the returned url in a browser (the user must do this step).","Then install the CLI GitHub App on the repo: GET /v1/github/install-url."],"retry":"after_fix"},{"code":"GITHUB_CANT_CREATE_REPO","httpStatus":409,"phase":"api","summary":"GitHub wouldn't create the repository: the name is taken on that account, or CLI's GitHub app hasn't been allowed to create repositories.","remediation":["Pick another repository name and try again.","If GitHub refused permission: accept the CLI GitHub App's updated permissions (Repository administration) in GitHub settings → Applications, then try again.","Or deploy the starter as-is and copy the code later from the app's Settings."],"retry":"after_fix"},{"code":"GITHUB_REPO_NOT_ACCESSIBLE","httpStatus":403,"phase":"api","summary":"The CLI GitHub App is not installed on this repository, or your GitHub account cannot see it.","remediation":["Install the CLI GitHub App on the repository (GET /v1/github/install-url), granting it access to this repo.","Check the owner/name spelling with GET /v1/github/repos."],"retry":"after_fix"},{"code":"WEBHOOK_SIGNATURE_INVALID","httpStatus":401,"phase":"api","summary":"The webhook signature did not verify.","remediation":["Check the webhook secret configured on the sender matches the server's."],"retry":"no"},{"code":"PAYMENT_REQUIRED","httpStatus":402,"phase":"api","summary":"This request needs an x402 payment.","remediation":["Pick an option from accepts[] in the response body (also base64 JSON in the PAYMENT-REQUIRED header).","Sign an EIP-3009 transferWithAuthorization for it and resend the same request with the PAYMENT-SIGNATURE header."],"retry":"after_fix"},{"code":"INSUFFICIENT_FUNDS","httpStatus":402,"phase":"preflight","summary":"Project balance does not cover one hour of the requested plan.","remediation":["Top up via x402: POST /v1/projects/:id/topup (pay the 402), or ask the user to fund the project.","Then retry the original request."],"retry":"after_topup"},{"code":"PAYMENT_INVALID","httpStatus":402,"phase":"api","summary":"The x402 payment payload failed verification.","remediation":["Re-sign the payment against the exact requirements in the latest 402 response (amount, payTo, asset, network)."],"retry":"after_fix"},{"code":"PAYMENT_REPLAYED","httpStatus":409,"phase":"api","summary":"This payment authorization was already used.","remediation":["Sign a new authorization with a fresh random nonce."],"retry":"after_fix"},{"code":"PAYMENT_SETTLEMENT_FAILED","httpStatus":502,"phase":"api","summary":"The facilitator could not settle the payment on-chain.","remediation":["Check your wallet has enough USDC on the required network, then retry once."],"retry":"yes"},{"code":"SPEND_CAP_EXCEEDED","httpStatus":403,"phase":"preflight","summary":"This agent wallet has reached the spend cap set by the project owner.","remediation":["Stop and ask the user (project owner) to raise your spend cap. Do not retry."],"retry":"no"},{"code":"ACCOUNT_REVIEW","httpStatus":403,"phase":"preflight","summary":"This project is on hold while CLI reviews unusual activity.","remediation":["Stop and tell the user. They need to contact CLI support to lift the hold. Do not retry."],"retry":"no"},{"code":"PROJECT_SUSPENDED","httpStatus":402,"phase":"preflight","summary":"The project ran out of credit and its services were stopped.","remediation":["Top up via x402. Services restart automatically when the balance is positive."],"retry":"after_topup"},{"code":"SOURCE_ACCESS_DENIED","httpStatus":422,"phase":"build","summary":"CLI could not get access to the source repository.","remediation":["Make sure the CLI GitHub App is still installed on the repo and has access to it (GET /v1/github/install-url).","Redeploy."],"retry":"after_fix"},{"code":"IMAGE_PULL_FAILED","httpStatus":422,"phase":"build","summary":"CLI couldn't pull the container image.","remediation":["Check the image name and tag exist (try `docker pull <image>` locally).","For a private image, set registry credentials: PATCH /v1/services/:id {\"registry\":{\"server\":\"ghcr.io\",\"username\":\"…\",\"password\":\"<token>\"}}. GHCR tokens need read:packages.","Redeploy."],"retry":"after_fix"},{"code":"BUILD_NO_BUILDER","httpStatus":422,"phase":"build","summary":"The builder could not detect how to build this source.","remediation":["Add a Dockerfile, or a recognised manifest at the repo root (package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml).","Commit it and redeploy."],"retry":"after_fix"},{"code":"BUILD_DEP_INSTALL","httpStatus":422,"phase":"build","summary":"Dependency installation failed.","remediation":["Read error.detail.evidence for the failing package.","Fix the version or name, regenerate and commit the lockfile, redeploy."],"retry":"after_fix"},{"code":"BUILD_COMPILE","httpStatus":422,"phase":"build","summary":"The code failed to compile or type-check.","remediation":["Fix the error at the file and line in error.detail.evidence, commit, redeploy."],"retry":"after_fix"},{"code":"BUILD_TIMEOUT","httpStatus":422,"phase":"build","summary":"The build took longer than the time limit.","remediation":["Speed up the build: cache dependencies, skip unneeded steps, or build a smaller image.","Or deploy a prebuilt image instead (source type image)."],"retry":"after_fix"},{"code":"BUILD_OOM","httpStatus":422,"phase":"build","summary":"The build ran out of memory.","remediation":["Reduce build parallelism (for example NODE_OPTIONS=--max-old-space-size or fewer workers), or move the service to a larger plan."],"retry":"after_fix"},{"code":"MISSING_ENV","httpStatus":422,"phase":"runtime","summary":"The app needs an environment variable that is not set.","remediation":["Set the variable named in error.detail.variable with PUT /v1/services/:id/env.","Ask the user for the value if you do not know it. Never invent secrets.","Redeploy."],"retry":"after_fix"},{"code":"PORT_MISMATCH","httpStatus":422,"phase":"runtime","summary":"The app is not listening on the port CLI routes to, or only on localhost.","remediation":["Make the app listen on process.env.PORT (or the PORT variable for your language) and host 0.0.0.0.","Redeploy."],"retry":"after_fix"},{"code":"HEALTHCHECK_TIMEOUT","httpStatus":422,"phase":"runtime","summary":"The app started but never answered the health check.","remediation":["Read the runtime logs for slow startup.","Make GET / (or the service healthcheckPath) return 2xx quickly, or set healthcheckPath to a route that does."],"retry":"after_fix"},{"code":"RUNTIME_CRASH","httpStatus":422,"phase":"runtime","summary":"The process exited during startup.","remediation":["Read the stack trace in error.detail.evidence and the runtime logs, fix the cause, redeploy."],"retry":"after_fix"},{"code":"RUNTIME_OOM","httpStatus":422,"phase":"runtime","summary":"The app was killed for using more memory than its plan allows.","remediation":["Move the service to a plan with more memory, or reduce memory use, then redeploy."],"retry":"after_fix"},{"code":"CONFIG_INVALID","httpStatus":422,"phase":"build","summary":"The cli.json in the repo isn't valid.","remediation":["error.detail.problems lists each problem with the field it's in. Fix cli.json and push again.","Allowed keys: build.command, build.dockerfile, deploy.startCommand, deploy.healthcheckPath, deploy.port, deploy.replicas, deploy.sleepAfterMinutes, watchPaths, cron[]. Remove the file to use dashboard settings."],"retry":"after_fix"},{"code":"VARIABLE_REFERENCE_MISSING","httpStatus":422,"phase":"build","summary":"A variable references a service or variable that doesn't exist.","remediation":["error.detail.missing lists each ${{service.KEY}} that didn't resolve. Check the service name (GET /v1/projects/:id) and the key.","Shared values are ${{shared.KEY}}: set them with PUT /v1/projects/:id/variables.","Fix the variable with PUT /v1/services/:id/env, then deploy again."],"retry":"after_fix"},{"code":"PLATFORM_ERROR","httpStatus":503,"phase":"any","summary":"CLI infrastructure failed. Not your fault.","remediation":["Retry with exponential backoff, at most 3 times. Escalate to the user if it persists."],"retry":"yes"},{"code":"UNKNOWN","httpStatus":422,"phase":"any","summary":"The failure did not match a known pattern.","remediation":["Read GET /v1/deploys/:id/logs in full and attempt a fix.","After 2 failed attempts, stop and report the logs to the user."],"retry":"after_fix"}]}