# 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`](https://carnival-staging.dev/docs/errors/UNAUTHORIZED.md) | 401 | no | This connection is no longer valid. |
| [`INSUFFICIENT_SCOPE`](https://carnival-staging.dev/docs/errors/INSUFFICIENT_SCOPE.md) | 403 | no | This connection is not allowed to do that. |
| [`ACCOUNT_SUSPENDED`](https://carnival-staging.dev/docs/errors/ACCOUNT_SUSPENDED.md) | 403 | no | This account cannot publish. |
| [`DEPLOYS_PAUSED`](https://carnival-staging.dev/docs/errors/DEPLOYS_PAUSED.md) | 503 | yes | Publishing is paused. |
| [`RATE_LIMITED`](https://carnival-staging.dev/docs/errors/RATE_LIMITED.md) | 429 | yes | A rate limit was reached. |
| [`LIVE_SITE_LIMIT_REACHED`](https://carnival-staging.dev/docs/errors/LIVE_SITE_LIMIT_REACHED.md) | 409 | no | Every live-site slot is in use. |
| [`SITE_NOT_FOUND`](https://carnival-staging.dev/docs/errors/SITE_NOT_FOUND.md) | 404 | no | No such site in this account. |
| [`SITE_NOT_LIVE`](https://carnival-staging.dev/docs/errors/SITE_NOT_LIVE.md) | 409 | no | That site is not live. |
| [`DEPLOY_NOT_FOUND`](https://carnival-staging.dev/docs/errors/DEPLOY_NOT_FOUND.md) | 404 | no | Unknown deploy_id. |
| [`DEPLOY_EXPIRED`](https://carnival-staging.dev/docs/errors/DEPLOY_EXPIRED.md) | 410 | no | This staged upload expired. |
| [`DEPLOY_ALREADY_FINALIZED`](https://carnival-staging.dev/docs/errors/DEPLOY_ALREADY_FINALIZED.md) | 409 | no | That deploy is already published. |
| [`IDEMPOTENCY_CONFLICT`](https://carnival-staging.dev/docs/errors/IDEMPOTENCY_CONFLICT.md) | 409 | no | This idempotency_key belongs to a different call. |
| [`PAYLOAD_TOO_LARGE`](https://carnival-staging.dev/docs/errors/PAYLOAD_TOO_LARGE.md) | 413 | no | Too much data in one call. |
| [`TOO_MANY_FILES_IN_CALL`](https://carnival-staging.dev/docs/errors/TOO_MANY_FILES_IN_CALL.md) | 413 | no | Too many files in one call. |
| [`FILE_TOO_LARGE`](https://carnival-staging.dev/docs/errors/FILE_TOO_LARGE.md) | 413 | no | A file is too large. |
| [`SITE_TOO_LARGE`](https://carnival-staging.dev/docs/errors/SITE_TOO_LARGE.md) | 413 | no | The site is too large. |
| [`TOO_MANY_FILES`](https://carnival-staging.dev/docs/errors/TOO_MANY_FILES.md) | 413 | no | The site has too many files. |
| [`INVALID_PATH`](https://carnival-staging.dev/docs/errors/INVALID_PATH.md) | 400 | no | A path is invalid. |
| [`DUPLICATE_PATH`](https://carnival-staging.dev/docs/errors/DUPLICATE_PATH.md) | 400 | no | A path appears more than once. |
| [`DISALLOWED_FILE_TYPE`](https://carnival-staging.dev/docs/errors/DISALLOWED_FILE_TYPE.md) | 415 | no | This file type is not allowed. |
| [`SERVER_CODE_NOT_ALLOWED`](https://carnival-staging.dev/docs/errors/SERVER_CODE_NOT_ALLOWED.md) | 422 | no | Server code or build configuration is not allowed. |
| [`INVALID_ENCODING`](https://carnival-staging.dev/docs/errors/INVALID_ENCODING.md) | 400 | no | A file could not be decoded. |
| [`HASH_MISMATCH`](https://carnival-staging.dev/docs/errors/HASH_MISMATCH.md) | 400 | no | A sha256 does not match its content. |
| [`INVALID_ARGUMENTS`](https://carnival-staging.dev/docs/errors/INVALID_ARGUMENTS.md) | 400 | no | The arguments are inconsistent. |
| [`MISSING_CONTENT`](https://carnival-staging.dev/docs/errors/MISSING_CONTENT.md) | 422 | no | Some files are missing. |
| [`MISSING_PARTS`](https://carnival-staging.dev/docs/errors/MISSING_PARTS.md) | 422 | no | Some pieces are missing. |
| [`MISSING_INDEX_HTML`](https://carnival-staging.dev/docs/errors/MISSING_INDEX_HTML.md) | 422 | no | index.html is missing. |
| [`CONTENT_REJECTED`](https://carnival-staging.dev/docs/errors/CONTENT_REJECTED.md) | 422 | no | The site was not published. |
| [`REJECTION_COOLDOWN`](https://carnival-staging.dev/docs/errors/REJECTION_COOLDOWN.md) | 429 | yes | Publishing is paused after repeated rejections. |
| [`INTERNAL_ERROR`](https://carnival-staging.dev/docs/errors/INTERNAL_ERROR.md) | 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](https://carnival-staging.dev/docs/tools.md)).