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 effective scope is insufficient.
`404`	The route or organization-scoped resource was not found.
`405`	The HTTP method is not supported for the public resource.
`409`	The operation conflicts with the current saved state or lifecycle state.
`413`	The request body exceeds the size limit, or a computation payload contains an array longer than 500 items.
`429`	A request budget was exceeded. Respect `Retry-After`.
`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.

Every error the API returns has the same shape: a requestId and an error object. error.code is for your code and error.message is for people. An oversized body (413) and a malformed Content-Length header (400) are rejected before the request reaches the API, so they return {"error": "<message>"} with no request ID; on /oauth2/* those two use the OAuth shape 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`.
`request_too_large`	`413`.
`rate_limit_exceeded`	`429`.
`result_not_representable`	`422`; a strict `payloadContract` admitted the request but cannot express the result. See Pin a strict contract.
`internal_error`	Any `5xx`.
`temporarily_unavailable`	`503`.
`request_failed`	Any other status.

The token endpoint uses the OAuth 2.0 error shape instead; its codes are under Authentication. MCP tool errors carry the same envelope inside the tool result; see Connect over MCP.

Validation details

error.details is present, one entry per failing field, on:

422: a request parameter failed validation.
400: the default computation boundary refused an inputs cell.
400: a strict payloadContract refused the request.
400: a saved-state scenario named a cell the engagement owns.

{
  "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 has three fields:

location is the dotted path to the field in your request. An array element appears as its index, so the second element of an array named rows is body.inputs.rows.1.
message says what was wrong, in one sentence.
code names the check that failed. On a 422 it is the parameter validator's error type, such as missing or less_than_equal. On a 400 it is a JSON Schema keyword, which you can check against the cell's entry in the computation reference.

The default boundary reports these keywords:

`code`	Meaning
`additionalProperties`	The cell is not published for the requested targets, or, in a scenario, the saved engagement owns it.
`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 profile, such as required, maximum, or pattern.

Submitted values are never echoed back in an error response.

Every /api/v1 response carries an X-Request-Id header, and MCP carries the same identifier in _meta["ca.filemark/requestId"]. Quote it when you write to support@filemark.ca about a failed request. Never include credentials or access tokens.

Error codes

Validation details#

Validation details