Error codes

The REST API and the MCP server return these HTTP status codes:

Status	Meaning
`400` or `422`	The request or one of its parameters is invalid.
`401`	The token is missing, invalid, expired, or unknown.
`403`	The client is disabled or the token lacks a required scope.
`404`	The route or resource was not found in your organization.
`405`	The HTTP method is not supported for the resource.
`409`	The operation conflicts with the current saved state or lifecycle state, or the same `Idempotency-Key` is still being processed.
`412`	The record changed since the version you sent in `If-Match` or `expectedResourceVersion`.
`413`	The request body exceeds the size limit, or a computation payload has an object with more than 1,000 members or more values than one request can carry.
`428`	A change to an existing record did not send its current version.
`429`	A rate limit was reached. Wait the number of seconds in `Retry-After` before retrying.
`500`	An unexpected server error occurred.
`502`	A required upstream service failed to complete the operation.
`503`	Authentication or a required service is temporarily unavailable. Respect `Retry-After` when present.

API errors contain a requestId and an error object with code and message. Use code for error handling and message for display.

An oversized body (413) or malformed Content-Length header (400) is rejected before API processing. These responses contain {"error": "<message>"} without a request ID. On /oauth2/*, they use the OAuth error format with error set to invalid_request.

`error.code`	Meaning
`invalid_request`	`400` or `422`. `error.details` names the failing fields when there are any.
`unauthorized`	`401`.
`forbidden`	`403`. The client is disabled.
`insufficient_scope`	`403`. The token lacks a scope the operation requires.
`not_found`	`404`.
`method_not_allowed`	`405`.
`conflict`	`409`. For writes, this includes a filed or signed-off engagement and an expired, spent or mismatched `confirmationToken`.
`idempotency_in_progress`	`409`. A request with the same `Idempotency-Key` is still running. Wait the number of seconds in `Retry-After`, then retry with the same key.
`resource_version_conflict`	`412`. Read the record again and retry with its current version.
`precondition_required`	`428`. Send the record's current version in `If-Match` or `expectedResourceVersion`.
`request_too_large`	`413`.
`rate_limit_exceeded`	`429`.
`result_not_representable`	`422`. A strict `payloadContract` accepted the request but cannot express the result. See Pin a strict contract.
`idempotency_key_reused`	`422`. The `Idempotency-Key` was already used for a different request. Send a new key.
`internal_error`	Any `5xx`.
`temporarily_unavailable`	`503`.
`request_failed`	Any other status.

The token endpoint's OAuth 2.0 errors are listed under Authentication. MCP tools return the API error object inside the tool result.

Validation details

error.details contains one entry per invalid field for these validation failures.

422: a request parameter failed validation.
400: an inputs cell failed the default computation checks.
400: the request failed strict payloadContract validation.
400: a scenario computation tried to override a cell the engagement controls.

{
  "requestId": "2f711c6917484e93b3c45a034a405c91",
  "error": {
    "code": "invalid_request",
    "message": "The computation input does not satisfy the selected strict contract.",
    "details": [
      {
        "location": "body.inputs.partnership.priorInterestAcb",
        "message": "Does not satisfy the 'maximum' constraint of the selected strict input schema.",
        "code": "maximum"
      }
    ]
  }
}

Each entry identifies the field and the failed check.

location is the dotted path to the field. Array indexes start at zero, so the second element of rows is body.inputs.rows.1.
message describes the problem.
code identifies the failed check. For 422, it is a parameter validation error such as missing or less_than_equal. For 400, it is a JSON Schema keyword listed in the cell's computation reference.

Default computation validation uses these keywords.

`code`	Meaning
`additionalProperties`	The cell is not published for the requested targets, or a scenario computation tried to override a cell the engagement controls.
`type`	The value is not the cell's published JSON type.
`required`	A rollover fact the computation needs was omitted or `null`. The computation reference marks these cells as always required.
`not`	Two facts in the request contradict each other.

A strict contract can report any keyword in the cell's strict schema, such as required, maximum, or pattern.

For help with a failed request, email support@filemark.ca with the X-Request-Id response header or MCP's _meta["ca.filemark/requestId"]. Keep credentials and access tokens out of the message.

Error codes

Validation details#

Validation details