Every Moda API error response carries a stableDocumentation Index
Fetch the complete documentation index at: https://docs.moda.app/llms.txt
Use this file to discover all available pages before exploring further.
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.
Branching guidance
- Branch on
type, not status code alone. Status codes collapse distinct failure modes;typeseparatesconflictfromidempotency_conflicteven though both surface as409. - Treat
codeas the narrow key. Use it for telemetry, runbook lookups, and per-error UI copy. Never displaymessageto end users — it is developer-facing and may change. - Retry only
upstream_errorandrate_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 |
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
Thetype 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. |