Error Reference - ContraForce

The v2 API surfaces every error as an RFC 7807 ProblemDetails document, served as application/problem+json. Switch on the code extension — it’s part of the contract and won’t move under your feet. The title and detail strings are human-readable and may be reworded between releases.

Response shape

{
  "type": "https://docs.contraforce.com/api-reference/errors",
  "title": "Resource not found",
  "status": 404,
  "detail": "Incident 'INC-12345' not found",
  "instance": "/api/v2/workspaces/6eca6a1f-b7d1-4bb8-a055-35ad6bb4b9b1/incidents/Sentinel/INC-12345",
  "code": "NOT_FOUND",
  "requestId": "0HNLBAGCRD4RN:00000003",
  "timestamp": "2026-04-15T20:00:00.0000000+00:00"
}

Field	Source	Description
`type`	RFC 7807	URI identifying the problem class. Points at this reference page (`https://docs.contraforce.com/api-reference/errors`); the `code` extension is the programmatic discriminator.
`title`	RFC 7807	Short, stable per-`code` summary.
`status`	RFC 7807	HTTP status code, mirrored in the response status line.
`detail`	RFC 7807	Per-instance message describing what went wrong.
`instance`	RFC 7807	URI of the failing request.
`code`	extension	Stable identifier you should switch on. See the catalogue below.
`requestId`	extension	Trace identifier for the failed request. Quote this when contacting support.
`timestamp`	extension	UTC ISO-8601 timestamp the failure was generated at.
`target`	extension, optional	Field or identifier the error refers to.
`errors`	extension, optional	Field-keyed validation error map. Empty key means an object-level error.

Validation responses

When binding fails or a FluentValidation rule rejects, the response includes an errors map:

{
  "type": "https://docs.contraforce.com/api-reference/errors",
  "title": "Validation failed",
  "status": 400,
  "detail": "One or more validation errors occurred.",
  "instance": "/api/v2/workspaces/.../incidents/Sentinel/INC-12345/comments",
  "code": "VALIDATION_ERROR",
  "errors": {
    "content": ["'Content' must not be empty."],
    "": ["At least one of source or workspaceId must be provided."]
  },
  "requestId": "0HNLBAGCRD4RN:00000007",
  "timestamp": "2026-04-15T20:00:00.0000000+00:00"
}

Keys are JSON property paths; the empty key carries object-level errors that aren’t tied to a specific field. A route or query value that names an enum member is matched without regard to case. One that matches no member is rejected the same way, keyed by the parameter name and listing what is accepted:

{
  "type": "https://docs.contraforce.com/api-reference/errors",
  "title": "Validation failed",
  "status": 400,
  "detail": "One or more validation errors occurred.",
  "instance": "/api/v2/workspaces/.../incidents/DefXDR/55022",
  "code": "VALIDATION_ERROR",
  "target": "source",
  "errors": {
    "source": ["'DefXDR' is not a valid value. Accepted values: Sentinel, DefenderXDR, QRadar, Splunk, CrowdStrike, SentinelOne."]
  },
  "requestId": "0HNLBAGCRD4RN:00000009",
  "timestamp": "2026-04-15T20:00:00.0000000+00:00"
}

A JSON body the API cannot read is rejected before any handler runs. The empty key in errors says what was wrong: the missing required properties, the JSON path of a value with the wrong type, or the line and position of malformed JSON.

{
  "type": "https://docs.contraforce.com/api-reference/errors",
  "title": "Validation failed",
  "status": 400,
  "detail": "The request body could not be read as JSON.",
  "instance": "/api/v2/workspaces/.../incidents/DefenderXDR/55025/comments",
  "code": "VALIDATION_ERROR",
  "errors": {
    "": ["Missing required properties: content."]
  },
  "requestId": "0HNLBAGCRD4RN:0000000B",
  "timestamp": "2026-04-15T20:00:00.0000000+00:00"
}

A request with no body at all on an endpoint that needs one returns the same code with detail set to A JSON request body is required. and target naming the parameter. A value that cannot be read from the route or query string returns detail A route or query value could not be read. A wrong Content-Type returns 415 UNSUPPORTED_MEDIA_TYPE, and a wrong verb 405 METHOD_NOT_ALLOWED, each with this envelope.

Error code catalogue

4xx — caller errors
5xx — service errors

Code	Status	When you see it	What to do
`VALIDATION_ERROR`	400	A required field is missing, malformed, or rejected by validation. The `errors` extension carries the per-field detail.	Inspect the `errors` map. Empty keys map to object-level errors; named keys map to JSON paths.
`BAD_REQUEST`	400	A 400 not classified as a validation failure (e.g. a malformed body the framework couldn’t parse at all).	Inspect `detail`. Confirm the body matches the documented shape.
`UNAUTHORIZED`	401	Missing or invalid `Authorization` header, revoked or rotated `clientSecret`, or a disabled service account.	Re-authenticate with valid credentials. If you rotated, update both halves of the credential.
`FORBIDDEN`	403	Authenticated, but the calling principal can’t perform this action on this resource.	Check that the credential carries the scope the endpoint requires and that the service account has the right workspace role. Some actions, such as changing organizational roles or creating service accounts, also need the service account’s organizational role to be Admin; the `detail` then reads like “Only an organization Admin can …”.
`INSUFFICIENT_SCOPE`	403	The credential is missing one of the scopes required by the endpoint.	Add the scope to the credential in the portal. Scopes follow the `{resource}:{action}` convention.
`INSUFFICIENT_WORKSPACE_ROLE`	403	The calling principal has no role on the target workspace.	Have an organization admin assign a workspace role to the service account.
`MFA_REQUIRED`	403	The user-flow path requires MFA from the configured IdP.	Complete the MFA challenge in the portal. Service accounts do not encounter this code.
`USER_NOT_REGISTERED`	403	The authenticated user is not registered in the ContraForce user store.	An organization admin must sync or invite the user before they can call the API.
`EXTENSION_NOT_ENABLED`	400	The endpoint requires an integration (e.g. Defender XDR, Jira) that hasn’t been consented and enabled for this workspace.	Enable the integration via the workspace configuration endpoints or in the portal.
`NOT_FOUND`	404	A workspace, incident, gamebook, or other addressed resource doesn’t exist or isn’t visible to the credential.	Verify the IDs in the path. For workspace-scoped routes, confirm the workspace is mapped to the service account.
`METHOD_NOT_ALLOWED`	405	Wrong HTTP verb on the route.	Check the endpoint reference for the correct verb.
`CONFLICT`	409	The resource version on the server differs from yours, the same operation was already performed, or two concurrent writes collided.	Refetch the resource and retry with the latest state.
`UNSUPPORTED_MEDIA_TYPE`	415	Wrong `Content-Type` header for the body shape.	Use `application/json` for JSON requests, `multipart/form-data` for operating procedure uploads.
`RATE_LIMITED`	429	Too many requests in the rolling window.	Honor `Retry-After` if present, otherwise back off exponentially.

Code	Status	When you see it	What to do
`INTERNAL_ERROR`	500	An unhandled exception.	Retry once; if persistent, contact support and quote the `requestId`.
`UPSTREAM_ERROR`	502	A downstream SIEM or EDR returned a 5xx, or our credential to the upstream is broken. Authentication failures from upstream services are also collapsed onto this code so we don’t leak which side of the integration is misconfigured.	Retry after a short backoff. If persistent, contact support — only we can resolve broken upstream credentials.
`TIMEOUT`	504	An upstream operation didn’t finish within our timeout window, or our HTTP client to the upstream timed out.	Retry after a short backoff. For long-running queries (KQL, advanced hunting), narrow the time window.

Mapping behavior

A few specific cases are worth calling out because they affect how you should design retries and surface failures to your own users.

Upstream 4xx is translated to a caller-facing 4xx

When a downstream SIEM rejects a request with a 4xx (404 for an unknown ID, 400 for an unparseable filter, 409 for a conflict, 429 for rate-limit, 408/504 for timeout), the v2 API surfaces that as the matching 4xx — NOT_FOUND, VALIDATION_ERROR, CONFLICT, RATE_LIMITED, TIMEOUT — rather than collapsing onto an opaque 502. That way your retry logic can act on what’s actually wrong.Only opaque or 5xx upstream failures stay as UPSTREAM_ERROR. Upstream 401/403 also stay opaque (they mean our credential to the upstream is broken; that’s not something you can fix).

Client-aborted requests do not produce a body

When the caller disconnects mid-request, the response is an empty 499 and no ProblemDetails body is written. Treat 499 as “request was cancelled before we could respond” — your client probably already knows.

Use requestId, not traceId

Some development-mode payloads previously carried a traceId extension from ASP.NET. The v2 contract is requestId only. Quote the requestId value when contacting support — we can correlate it to backend logs without you needing to share anything else.

Correlating with our logs

Every requestId is also recorded in our backend logs. Including it in support requests dramatically shortens triage:

Hello, I’m seeing intermittent 502 UPSTREAM_ERROR on POST /api/v2/incidents/across-workspaces. Example requestId: 0HNLBAGCRD4RN:00000003 at 2026-04-15T20:00:00Z.

We can pull the full backend trace and pinpoint the failure without needing the request body or your credentials.

​Response shape

​Validation responses

​Error code catalogue

​Mapping behavior

​Correlating with our logs

Response shape

Validation responses

Error code catalogue

Mapping behavior

Correlating with our logs