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

# Errors

> The standard error envelope and error codes returned by the ModernLoop Platform API and MCP server.

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

```json theme={"dark"}
{
  "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.