Error codes¶

Codes the MCP server may surface in ErrorResponse.error. Three classes:

SaldeoSMART-issued — returned in <ERROR_CODE> from the API.
Synthetic — minted by the client when a transport / parsing / validation problem prevented the API call.
Per-item — the envelope succeeded (STATUS=OK) but individual batch items failed; one entry per failed item in ErrorResponse.details[].

SaldeoSMART-issued codes¶

Code	Meaning	Recovery
`4401`	No SEARCH_POLICY found in file.	The `document/search` request body is missing `<SEARCH_POLICY>` or has the wrong tag (`<POLICY>`). Confirmed via the `_build_search_xml` builder — fix the input shape.

Synthetic codes¶

Defined in src/saldeosmart_mcp/errors.py and src/saldeosmart_mcp/http/client.py.

Code	Constant	Meaning
`HTTP_<status>`	(transport)	Non-2xx HTTP status with no `<RESPONSE>` envelope. Status drives the suffix (e.g. `HTTP_500`, `HTTP_403`).
`PARSE_ERROR`	(transport)	2xx body wasn't valid XML — usually an HTML error page from a proxy or load balancer. First 500 chars in `message`.
`UNKNOWN`	(transport)	Envelope had `<STATUS>ERROR</STATUS>` but `<ERROR_CODE>` was empty.
`EMPTY_INPUT`	`ERROR_EMPTY_INPUT`	Tool short-circuited because a required list argument was empty.
`INVALID_INPUT`	`ERROR_INVALID_INPUT`	Builder-level invariant violation (e.g. attachment-count mismatch).
`MISSING_CRITERIA`	`ERROR_MISSING_CRITERIA`	Search/lookup tool called without enough criteria to be specific.
`TOO_MANY_DOCUMENTS`	`ERROR_TOO_MANY_DOCUMENTS`	Batch endpoint asked to process more than its per-request cap.
`ATTACHMENT_NOT_FOUND`	`ERROR_ATTACHMENT_NOT_FOUND`	`Attachment.path` does not exist on disk.
`ATTACHMENT_PERMISSION_DENIED`	`ERROR_ATTACHMENT_PERMISSION_DENIED`	`Attachment.path` exists but isn't readable by the server process.

Per-item validation errors¶

Batch operations (*.merge, update_documents, import_documents, …) succeed at the envelope level even when individual items fail. Each failed item is an entry in ErrorResponse.details[]:

{
  "error": "VALIDATION",
  "message": "some items failed",
  "details": [
    {"status": "NOT_VALID", "path": "VAT_NUMBER", "message": "required field", "item_id": "2"}
  ]
}

The path field names the offending element from the request XML; use it to locate which field of which input model needs fixing. See iter_item_errors in src/saldeosmart_mcp/errors.py for the walker.

Authoritative source¶

SaldeoSMART's official error-code list lives in their API documentation portal (the same place where the API token is generated). When in doubt, consult that — and append anything useful to docs/_data/error_meanings.yaml.