Error Contract

All errors and business warnings use a single contract:

{
  "messageCode": "CONTRACT_STATE_INVALID",
  "severity": "ERROR",
  "params": {
    "contractId": "ctr_01J8ZK4T2M",
    "currentState": "TERMINATED",
    "attemptedAction": "APPROVE"
  },
  "traceId": "8f4a2c1e-9b3d-4e7f-a1c2-5d6e7f8a9b0c",
  "message": "The contract does not allow this action in its current state."
}

Field	Type	Description
messageCode	string	Stable machine-readable code. Build your integration logic on this field.
severity	ERROR | WARNING | INFO	Whether the operation was rejected or accepted with a caveat.
params	object	Structured, code-specific parameters for rendering your own message.
traceId	string	End-to-end trace id; include it in support requests.
message	string	Human-ready text resolved from the catalog in the request language.

Three-locale message catalog

The message field is resolved from a central catalog available in Turkish, English and Arabic, selected via Accept-Language (tr is the default):

POST /api/v1/contracts HTTP/1.1
Accept-Language: en

Two consequences:

1. Channels never invent copy. Portal, console and your integration can show the same text for the same messageCode.
2. Text may improve; codes never change. messageCode values are stable and covered by the N-5 compatibility commitment.

HTTP status codes

Status	Meaning
400	Structural validation error
401	Authentication failed / token expired
403	Insufficient role/permission
404	Resource not found (within tenant scope)
409	Business conflict (state machine, four-eyes, idempotency)
422	Business validation failed (e.g. derived field posted)
500	Unexpected error — report with traceId