> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moda.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Error codes

> The full catalog of stable error codes returned by the Moda public API. Every error response carries a `code` field keyed to this page.

Every Moda API error response carries a stable `code` field — a machine-readable string that never changes once published. This page lists every code the API can return, along with the high-level `type` SDKs branch on and the HTTP status code each maps to.

For the shape of the error envelope itself (`type`, `code`, `message`, `doc_url`, `request_id`, etc.), see [Error format](/api-reference#error-format).

## Branching guidance

* **Branch on `type`, not status code alone.** Status codes collapse distinct failure modes; `type` separates `conflict` from `idempotency_conflict` even though both surface as `409`.
* **Treat `code` as the narrow key.** Use it for telemetry, runbook lookups, and per-error UI copy. Never display `message` to end users — it is developer-facing and may change.
* **Retry only `upstream_error` and `rate_limited`.** Everything else is either permanent or requires a request fix; retrying will not help.
* **Always log `request_id`.** It is the single field that lets Moda support trace a specific failure across logs and Sentry.

## Catalog

| Code                          | Type                   | HTTP  |
| ----------------------------- | ---------------------- | ----- |
| `authentication`              | `authentication`       | `401` |
| `brand_kit_folder_protected`  | `permission`           | `403` |
| `canvas_not_slides_for_theme` | `invalid_request`      | `400` |
| `conflict`                    | `conflict`             | `409` |
| `file_name_conflict`          | `conflict`             | `409` |
| `file_not_found`              | `not_found`            | `404` |
| `folder_circular_reference`   | `invalid_request`      | `400` |
| `folder_name_conflict`        | `conflict`             | `409` |
| `folder_not_found`            | `not_found`            | `404` |
| `folder_team_mismatch`        | `permission`           | `403` |
| `folder_write_denied`         | `permission`           | `403` |
| `idempotency_conflict`        | `idempotency_conflict` | `409` |
| `internal_error`              | `internal_error`       | `500` |
| `invalid_id_format`           | `invalid_request`      | `400` |
| `invalid_request`             | `invalid_request`      | `400` |
| `member_cap_exceeded`         | `permission`           | `403` |
| `method_not_allowed`          | `invalid_request`      | `405` |
| `not_found`                   | `not_found`            | `404` |
| `organization_access_denied`  | `permission`           | `403` |
| `organization_not_found`      | `not_found`            | `404` |
| `permission`                  | `permission`           | `403` |
| `rate_limited`                | `rate_limited`         | `429` |
| `scraping_user_error`         | `unprocessable`        | `422` |
| `share_link_not_found`        | `not_found`            | `404` |
| `share_link_revoked`          | `not_found`            | `404` |
| `team_access_denied`          | `permission`           | `403` |
| `team_not_found`              | `not_found`            | `404` |
| `unprocessable`               | `unprocessable`        | `422` |
| `unsupported_version`         | `invalid_request`      | `400` |
| `upstream_error`              | `upstream_error`       | `502` |
| `user_already_exists`         | `conflict`             | `409` |
| `validation_failed`           | `unprocessable`        | `422` |

## Type reference

The `type` field is a closed set. SDKs may translate types to typed exceptions; new `code` values may be added to an existing type without notice, so always include a default branch.

| Type                   | Description                                                                      |
| ---------------------- | -------------------------------------------------------------------------------- |
| `invalid_request`      | Request was malformed, missing a required field, or used an unsupported version. |
| `authentication`       | Auth failed — missing, malformed, or revoked credentials.                        |
| `permission`           | Authenticated, but not authorized for this resource or scope.                    |
| `not_found`            | The referenced resource does not exist or has been removed.                      |
| `conflict`             | The request conflicts with current resource state (e.g. name collision).         |
| `idempotency_conflict` | An `idempotency_key` was reused with a different request body.                   |
| `unprocessable`        | Request was well-formed but failed validation or upstream extraction.            |
| `rate_limited`         | Caller exceeded the rate limit — back off per `Retry-After`.                     |
| `upstream_error`       | A required upstream service failed transiently.                                  |
| `internal_error`       | Unexpected server error — include `request_id` if reporting.                     |