Error codes
A failed Carnival tool call returns a result with isError: true (the reply's HTTP status is still 200). Its JSON has an error object: code, message, hint (what to do), retryable, docs_url (a page below), request_id, and for some codes retry_after_seconds, limit, field, reason or max_files_per_call; fields such as deploy_id, missing or live_sites sit next to it.
Read error.code and error.hint, fix the input and call again; repeat an unchanged call only when retryable is true. HTTP is the semantic class of the error.
| Code | HTTP | Retry | Meaning |
|---|---|---|---|
UNAUTHORIZED |
401 | no | This connection is no longer valid. |
INSUFFICIENT_SCOPE |
403 | no | This connection is not allowed to do that. |
ACCOUNT_SUSPENDED |
403 | no | This account cannot publish. |
DEPLOYS_PAUSED |
503 | yes | Publishing is paused. |
RATE_LIMITED |
429 | yes | A rate limit was reached. |
LIVE_SITE_LIMIT_REACHED |
409 | no | Every live-site slot is in use. |
SITE_NOT_FOUND |
404 | no | No such site in this account. |
SITE_NOT_LIVE |
409 | no | That site is not live. |
DEPLOY_NOT_FOUND |
404 | no | Unknown deploy_id. |
DEPLOY_EXPIRED |
410 | no | This staged upload expired. |
DEPLOY_ALREADY_FINALIZED |
409 | no | That deploy is already published. |
IDEMPOTENCY_CONFLICT |
409 | no | This idempotency_key belongs to a different call. |
PAYLOAD_TOO_LARGE |
413 | no | Too much data in one call. |
TOO_MANY_FILES_IN_CALL |
413 | no | Too many files in one call. |
FILE_TOO_LARGE |
413 | no | A file is too large. |
SITE_TOO_LARGE |
413 | no | The site is too large. |
TOO_MANY_FILES |
413 | no | The site has too many files. |
INVALID_PATH |
400 | no | A path is invalid. |
DUPLICATE_PATH |
400 | no | A path appears more than once. |
DISALLOWED_FILE_TYPE |
415 | no | This file type is not allowed. |
SERVER_CODE_NOT_ALLOWED |
422 | no | Server code or build configuration is not allowed. |
INVALID_ENCODING |
400 | no | A file could not be decoded. |
HASH_MISMATCH |
400 | no | A sha256 does not match its content. |
INVALID_ARGUMENTS |
400 | no | The arguments are inconsistent. |
MISSING_CONTENT |
422 | no | Some files are missing. |
MISSING_PARTS |
422 | no | Some pieces are missing. |
MISSING_INDEX_HTML |
422 | no | index.html is missing. |
CONTENT_REJECTED |
422 | no | The site was not published. |
REJECTION_COOLDOWN |
429 | yes | Publishing is paused after repeated rejections. |
INTERNAL_ERROR |
500 | yes | Temporary problem at Carnival. |
Not in this list: answers from the /mcp endpoint itself (HTTP 401, 403, 405, 413, 429) and schema failures, which come back as uncoded Input validation error: … text; fix the arguments to match the tool's schema (tools).