Errors - ModernLoop Platform API

Every REST endpoint and MCP tool reports failures with the same JSON envelope:

{
  "error": {
    "code": "CANNOT_UPDATE_SYNC_MANAGED_FIELDS",
    "message": "These fields are managed by an external sync source (directory/SCIM) and cannot be updated via the API: title (SCIM).",
    "docs_url": "https://docs.modernloop.io/errors",
    "details": [{ "field": "title", "source": "SCIM" }]
  }
}

code — a stable machine-readable error code from the table below. Branch on this, never on message.
message — a human-readable explanation. Wording may change without notice.
docs_url — optional link to relevant documentation.
details — optional list of machine-readable entries carrying structured context, such as the specific fields a write was rejected for. Codes that populate details document the entry shape below.

Error codes

Code	Meaning	How to recover
`UNAUTHENTICATED`	Authentication was missing or invalid.	Reconnect and complete OAuth.
`INSUFFICIENT_SCOPE`	The token lacks permission for this operation.	Reconnect with the required scope or use a permitted operation.
`VALIDATION_FAILED`	Input did not match the request schema.	Correct the listed fields and retry.
`INVALID_CURSOR`	The cursor does not belong to these filters.	Restart the list request and reuse the cursor only with unchanged filters.
`PAYLOAD_TOO_LARGE`	The request body exceeds the size limit.	Reduce the request payload.
`NOT_FOUND`	The resource is absent or outside this organization.	Discover a valid ID first.
`IDEMPOTENCY_KEY_REQUIRED`	The create request needs an idempotency key.	Generate a fresh key for this logical create.
`IDEMPOTENCY_KEY_REUSED`	The idempotency key was used with a different payload.	Use a fresh key for the changed request.
`RATE_LIMITED`	Too many requests were made.	Wait and retry with backoff.
`CONFLICT`	The requested state transition conflicts with current data.	Read the object and resolve the conflict before retrying.
`CANNOT_UPDATE_SYNC_MANAGED_FIELDS`	A profile field is managed by directory or SCIM sync and cannot be updated via the API.	Drop the fields listed in `details`, or change the field’s sync source in ModernLoop settings and update the value in the source system.
`NOT_IMPLEMENTED`	This operation is not available.	Use a supported operation.
`INTERNAL`	ModernLoop encountered an unexpected error.	Retry later or contact support.
`UPSTREAM_TIMEOUT`	An upstream ModernLoop dependency timed out.	Retry the idempotent operation later.

`CANNOT_UPDATE_SYNC_MANAGED_FIELDS` details

Returned with HTTP 409 by PATCH /v1/users/{userId} (and the update_user MCP tool) when the request writes profile fields whose source of truth the organization has delegated to an external sync source. All rejected fields are reported in one response so a single retry can fix the request. Each details entry has:

field — the rejected request field: name, title, manager, or linkedin_url.
source — the configured source of truth: DIRECTORY or SCIM.

A field is rejected even when the submitted value equals the stored value, so read-modify-write clients should omit sync-managed fields rather than echo them back.

​Error codes

​CANNOT_UPDATE_SYNC_MANAGED_FIELDS details

Error codes

`CANNOT_UPDATE_SYNC_MANAGED_FIELDS` details