Error codes for branching in your agent
All errors from the MCP server have a fixed structure. The code field is stable and intended for switch statements in agent code — it doesn't change with localisation or with minor wording adjustments.
{
"statusCode": 4xx,
"error": "<short_label>",
"message": "Human-readable message (PL)",
"code": "STABLE_MACHINE_READABLE_CODE",
"details": { ... optional context field }
}22 codes. Alphabetical sort for quick lookup.
AI_DEPLOY_GLOBALLY_DISABLEDHTTP 503retry: After Retry-AfterGlobal admin kill switchexpand_more
What happened: Global admin kill switch — AI Deploy disabled for all accounts (e.g. an incident is ongoing).
What to do in the agent: Wait. Status: /status. After restoration, the agent can retry the last mutation with the same Idempotency-Key.
AI_DEPLOY_NOT_ENABLEDHTTP 403retry: NoAccount tier = noneexpand_more
What happened: The customer account has tier ai_deploy = none. All write calls are blocked.
What to do in the agent: Direct the user to the contact form (subject ai-deploy-beta) — an admin must change the tier to sandbox/beta/full.
AI_DEPLOY_TIER_TOO_LOWHTTP 403retry: NoTier=sandbox attempts write/deleteexpand_more
What happened: The account is on sandbox tier, but the called tool requires beta/full (e.g. install_wordpress, set_dns_records, delete_domain).
What to do in the agent: Perform a read-only operation or request a tier promotion via the contact form.
APP_INSTALL_FAILEDHTTP 500retry: YesInstall (e.g. WordPress) failedexpand_more
What happened: Installation (e.g. WordPress) failed while executing the steps.
What to do in the agent: Check get_job_status → result.error.details. Most often: no disk space, unavailable mirror.
APP_INSTALL_PREFLIGHT_FAILEDHTTP 422retry: NoPreflight: no disk space, outdated PHP versionexpand_more
What happened: Preflight before install — no space, outdated PHP version, invalid binding to the website.
What to do in the agent: Show the user error.details. Most often the PHP version needs changing or space needs freeing.
APP_TYPE_NOT_SUPPORTEDHTTP 400retry: NoUnsupported application typeexpand_more
What happened: Attempt to install an application we do not support.
What to do in the agent: List of supported applications: list_packages.supported_apps. WordPress is supported; other CMSes are added gradually.
CONFIRMATION_REQUIREDHTTP 400retry: NoMissing confirm=true in a destructive callexpand_more
What happened: The destructive call did not include the confirm: true field.
What to do in the agent: After showing the impact to the user and obtaining their consent, send confirm: true together with preview_token.
DATABASE_IN_USE_BY_APPHTTP 409retry: NoAttempt to delete a database used by an appexpand_more
What happened: Attempt to delete a database used by an application (e.g. an installed WordPress).
What to do in the agent: First delete the application (delete_app, when available) or detach the database from the application.
IDEMPOTENCY_KEY_INVALIDHTTP 400retry: NoInvalid Idempotency-Key formatexpand_more
What happened: Idempotency-Key must be UUID v4. Empty or invalid format.
What to do in the agent: Generate a UUID v4 on the client side and repeat the request.
IDEMPOTENCY_KEY_REUSEDHTTP 409retry: NoSame key, different body within 24hexpand_more
What happened: The client reused the same Idempotency-Key with a different request body within the last 24h.
What to do in the agent: Generate a new key for changed data, or send the identical body — then you'll receive the cached response.
JOB_ALREADY_FINISHEDHTTP 409retry: NoAttempt to modify a terminal jobexpand_more
What happened: Attempt to modify a job with a terminal status (succeeded/failed/cancelled).
What to do in the agent: The job has finished — read the result.
JOB_NOT_FOUNDHTTP 404retry: NoInvalid job UUIDexpand_more
What happened: Invalid job UUID — no such job exists in the system.
What to do in the agent: Check that you're using the job_id from an asynchronous tool's response (install_wordpress, request_ssl).
JOB_OWNERSHIP_MISMATCHHTTP 403retry: NoJob belongs to a different userexpand_more
What happened: The job belongs to a different user.
What to do in the agent: Same as PREVIEW_TOKEN_OWNERSHIP_MISMATCH — critical client error.
PREVIEW_TOKEN_ALREADY_CONSUMEDHTTP 409retry: NoSingle-use token already consumedexpand_more
What happened: The token is single-use — it has already been used in a previous call.
What to do in the agent: If the operation actually succeeded, check the result. If not — call preview_* again.
PREVIEW_TOKEN_EXPIREDHTTP 410retry: NoToken older than 10 minexpand_more
What happened: The token has exceeded its 600-second (10-minute) TTL.
What to do in the agent: Call preview_* again and use the new token immediately.
PREVIEW_TOKEN_MISSINGHTTP 400retry: NoMissing token in a destructive callexpand_more
What happened: Missing preview_token in a destructive call (e.g. delete_domain without a token).
What to do in the agent: First call preview_delete_*, show the user the impact field, then call delete_* with the token.
PREVIEW_TOKEN_NOT_FOUNDHTTP 404retry: NoToken does not exist or has expiredexpand_more
What happened: The token does not exist in the database (was never issued).
What to do in the agent: Call preview_* to obtain a fresh token.
PREVIEW_TOKEN_OWNERSHIP_MISMATCHHTTP 403retry: NoToken belongs to a different user_idexpand_more
What happened: The token was issued for a different user_id than the token authenticating the request.
What to do in the agent: Critical client error — the agent is trying to use somebody else's token. Abort the session and report to security@mdiv.pl.
PREVIEW_TOKEN_RESOURCE_MISMATCHHTTP 403retry: NoToken issued for a different resource_idexpand_more
What happened: The token was issued for a different resource_id than the one in the current call.
What to do in the agent: Call preview_* for the correct resource. Do not try to `shift` the token to a different object.
RATE_LIMITEDHTTP 429retry: After Retry-AfterRate limit exceeded (60/min, install 5/min)expand_more
What happened: The token has exhausted its limit (60/min default or 5/min for install ops).
What to do in the agent: Respect the Retry-After header. Ignoring limits results in the token being paused.
SSL_ISSUE_FAILEDHTTP 422retry: YesLet's Encrypt validation failedexpand_more
What happened: Let's Encrypt rejected validation (e.g. DNS hasn't propagated yet, missing A record, .well-known file unavailable).
What to do in the agent: Check error.details (challenge type, propagation_check). After fixing DNS, retry request_ssl.
SSL_RENEW_FAILEDHTTP 422retry: YesSSL renewal failedexpand_more
What happened: Certificate auto-renew failed — most often due to changed DNS records.
What to do in the agent: Check the DNS configuration and retry request_ssl. mDiv automatically retries every 24h.