Help Center

Search
Log in
Sign up

Help Center

Log in
Sign up
Table of Contents

API & SCIM Errors

Workspace API and SCIM use different error formats. Check both the HTTP status and the returned body.

Workspace API

Procedure errors are plain text. The dispatcher returns an explicit procedure error status where one is assigned; otherwise it returns 500. The older project and user procedures frequently use 500 for invalid arguments or access denial, so do not automatically retry every 500.

Condition

Status / action

Unknown procedure

404; verify the procedure name.

Invalid input on revokeWorkspaceUserAccess

400; correct workspaceId and userId.

Missing, invalid, rotated or revoked key on revokeWorkspaceUserAccess

401 when key authentication is reached; replace or correct the key.

Wrong workspace or insufficient revoke authority

403; verify the workspace and current admin authority. A disabled target Workspace API can also return 403.

Changing an existing global name through upsertWorkspaceUser

403: Workspace access updates cannot change existing global account profiles. Omit fullName for access-only updates; use the supported global-profile flow for a name change.

Last-admin revoke

409; ensure another administrator remains.

Revoke billing dependency failure

503; the removal did not complete. Retry after recovery.

Other procedure validation/authentication failures

Generally 500 in current code; inspect the plain-text message and fix the cause.

Unexpected failure

500; reconcile the outcome before retrying a non-idempotent operation.

HTTP 400

workspaceId must be a non-empty stable identifier

SCIM

SCIM errors use application/scim+json, the Error schema, a string status and a safe detail. Some also include scimType.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "400",
  "detail": "userName and work email must identify the same source email",
  "scimType": "invalidValue"
}

Status

Typical cause

Action

400

Malformed JSON, unsupported attribute/path/filter, invalid role, conflicting email aliases

Correct the mapping or request. Use only supported fields and equivalent userName/work email.

401

Missing, invalid, expired, rotated or revoked token; wrong credential type; SCIM capability disabled

Confirm enablement and replace the token as appropriate. The response includes a Bearer challenge.

403

Insufficient scope, inactive workspace or local admin block

Check setup and contact a workspace admin. SCIM cannot clear a local veto.

404

Unknown or foreign-source User ID

Use the SCIM ID returned to this provisioning source, not a canonical Workspace API user ID.

405

Unsupported method, including terminal DELETE

Use active=false for deprovisioning. DELETE changes nothing.

409

Duplicate create, conflicting correlation or another managing source

Read the existing source-owned User and resolve the conflict; do not create another account blindly.

413

Request exceeds the 1 MiB body limit

Reduce request size.

415

Unsupported content type

Use application/scim+json or application/json for writes.

503

Required billing reconciliation failed

Provisioning did not complete. Retry after the dependency recovers.

500

Unexpected provisioning failure

Retry cautiously and contact Diggle if repeated.

Connection and mapping checks

  • Workspace API keys, SCIM tokens and Microsoft access tokens are different credentials. Verify the credential type, workspace, provisioning source and tenant.
  • Test Connection checks connectivity and authentication, not user creation, role mapping or offboarding. Inspect the export operation and test the full lifecycle with a dedicated user.
  • Do not remove standard SCIM schemas to work around “The schemas attribute is not supported”. Check the supported schema URIs and remove unsupported attributes; if a valid standard request is rejected, ask Diggle to check the deployed version and request contract.
  • Initial provisioning does not require an approved email domain. Identity conflicts and local access blocks still require resolution.
  • A newly created token does not automatically renew an expired or invalid pending SCIM activation. See Microsoft Entra SSO.

Retry guidance

Use bounded retries with increasing delay for confirmed transient failures. Verify state after a lost response. For SCIM POST, query the source-owned User before creating again; a committed duplicate returns 409. Use the retained SCIM ID for updates. Do not invent new IDs or change email to bypass a conflict.

Do not automatically retry createProject after an ambiguous result. Equivalent user upserts and workspace revocation are designed for repeat calls. A local block or unsupported operation requires a configuration or administrator action, not more retries.

When contacting Diggle, provide the procedure/path, approximate time, HTTP status, a redacted error description and relevant tracking/change IDs. Never include keys, tokens, passwords, cookies, login codes or complete Authorization headers.

Related articles