Errors

A non-2xx status indicates that the request did not complete successfully. Endpoint pages list the exact responses declared for each operation.

Documented error statuses

• 400 — Cannot stop; Invalid or expired token; Invalid request (missing or conflicting parameters); Invalid token or incomplete setup; Invalid/expired token or validation error; Job has no snapshotted YAML, the snapshot fails to parse, or task_versions_snapshot is corrupt; Job run cannot be resumed (wrong status); Missing api_key (VALIDATION_ERROR) or key rejected by Anthropic (INVALID_KEY); Missing pending session cookie or TOTP code. Messages distinguish the two cases so the client can recover (re-login vs re-enter code).; Not a cardamom connector; Not a cardamom connector, BYOA required, or invalid body; Run cannot be stopped; Run is currently active; TOTP already configured, or enrollment already started and force was not provided; Unsupported connector type; Validation error; Validation error (invalid definition); Validation error or cancelled export; Validation or Saffron error; Validation or parse error
• 401 — Current password incorrect; Invalid TOTP code; Not authenticated
• 403 — Insufficient permissions; Method is not read-only; Method not allowed for data exploration; Public input not enabled for this dashboard; Requires admin or superadmin; Widget does not allow public actions
• 404 — Not found; Resource not found
• 409 — File already exists and overwrite was not set; In-flight action or cooldown
• 413 — File too large
• 415 — Unsupported file extension for connector type
• 429 — Too many requests
• 500 — Catalog list failed; Connect session mint failed; Export execution failed; Introspection failed; Query execution failed
• 501 — AI not configured; Connector type does not support file uploads
• 502 — Anthropic unreachable — key not validated or persisted (ANTHROPIC_UNREACHABLE)
• 503 — Public dashboard actions disabled on this server; Public dashboard input disabled on this server; Public dashboards disabled; Public dashboards disabled on this server

Reusable responses

NotFound

Resource not found

Content type: application/json

• Reference: Error
  • Type: object
  • Properties:
    • error (string)
      • Example: NOT_FOUND
    • message (string)
      • Example: Resource not found

Example:

{
  "error": "NOT_FOUND",
  "message": "Resource not found"
}

ValidationError

Validation error

Content type: application/json

• Reference: Error
  • Type: object
  • Properties:
    • error (string)
      • Example: NOT_FOUND
    • message (string)
      • Example: Resource not found

Example:

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid input"
}

Unauthorized

Not authenticated

Content type: application/json

• Reference: Error
  • Type: object
  • Properties:
    • error (string)
      • Example: NOT_FOUND
    • message (string)
      • Example: Resource not found

Example:

{
  "error": "AUTH_ERROR",
  "message": "Not authenticated"
}

TooManyRequests

Too many requests

Content type: application/json

• Reference: Error
  • Type: object
  • Properties:
    • error (string)
      • Example: NOT_FOUND
    • message (string)
      • Example: Resource not found

Example:

{
  "error": "RATE_LIMITED",
  "message": "Too many failed TOTP attempts. Try again later."
}

Error schemas

Error

• Reference: Error
  • Type: object
  • Properties:
    • error (string)
      • Example: NOT_FOUND
    • message (string)
      • Example: Resource not found

ConnectorCheckError

• Reference: ConnectorCheckError
  • Type: object
  • Properties:
    • name (string, required) — Error class name (e.g. MongoServerError)
    • message (string, required) — Raw error message
    • code (string) — Driver/SDK error code