Tracer error list

Tracer APIs return a structured error object with a stable code, HTTP status, and message so you can diagnose issues and route them to the right team.

The Tracer API returns errors as an RFC 9457 problem details object, served with the application/problem+json content type:

{
   "type": "https://errors.lerian.studio/v1/<error_code>",
   "title": "<error_title>",
   "status": <http_status>,
   "detail": "<error_message>",
   "code": "<error_code>"
}

Field definitions

• type: A URI that identifies the error type, built as https://errors.lerian.studio/v1/ followed by the error code.
• title: A brief summary of the issue.
• status: The HTTP status code of the response.
• detail: Detailed guidance for resolving the error. The tables below list this content in the message column.
• code: A unique, stable identifier for the error. It is usually a four-digit numeric string drawn from the shared platform error registry (for example, 0347). API-key authentication failures use the literal string Unauthenticated (see the note below). Access Manager and Tenant Manager refusals use their own codes, including the codes in Capacity and authentication errors.
• entityType: The entity the error relates to (for example, Rule). Only present when applicable.
• message: The human-readable reason, exposed verbatim as a top-level field. Present on 413 Payload Too Large and 504 Gateway Timeout responses.

For server-side errors (HTTP 5xx), title and detail carry generic values. Access Manager and Tenant Manager refusals keep their own title and detail. Use code and type to identify the error. For 504 timeouts, the top-level message field still carries the specific reason.

Field-level validation

Struct-level field validation failures return code 0009 with the title Validation Error and a detail that names the specific field and constraint, for example scope at index 0: scheme must be 1 to 50 characters of A-Z, 0-9, _ or - after trimming and upper-casing.

Examples:

Missing required field

{
   "type": "https://errors.lerian.studio/v1/0009",
   "title": "Validation Error",
   "status": 400,
   "detail": "name is a required field",
   "code": "0009"
}

Two response families keep a legacy flat {"code", "title", "message"} shape instead of the problem details object. Middleware that runs before the API layer emits them. Authentication failures: a missing or invalid API key returns HTTP 401 with "code": "Unauthenticated", "title": "Unauthorized", and "message": "API Key missing or invalid". Match on the literal Unauthenticated string. A Bearer token that parses but lacks the required sub claim returns HTTP 401 with "code": "0474". Tenant capacity: code 0466 returns HTTP 503 in the same flat shape.

General errors

---

Any Tracer API endpoint can return these errors.

code	title	message
0009	Missing Fields in Request	Your request is missing one or more required fields: %v. Please refer to the documentation to ensure all necessary fields are included in your request.
0046	Internal Server Error	The server encountered an unexpected error. Please try again later or contact support.
0065	Invalid Path Parameter	One or more path parameters are in an incorrect format. Please check the following parameters %v and ensure they meet the required format before trying again.
0082	Invalid Query Parameter	One or more query parameters are in an incorrect format. Please check the following parameters ‘%v’ and ensure they meet the required format before trying again.
0094	Bad Request	The request body is malformed or contains invalid JSON. Please verify the syntax and try again.
0143	Payload Too Large	payload too large: exceeds 100KB limit
0183	Nothing to Update	No updatable fields were provided. Please include at least one field to update.
0330	Context Cancelled	Context cancelled / service unavailable.
0484	Route Not Found	The requested route does not exist. Please verify the HTTP method and path and try again.
0485	Method Not Allowed	The HTTP method is not allowed for the requested route. Please verify the method and try again.
0497	Request Header Fields Too Large	The request header fields are too large. Please reduce the size of the request headers and try again.

Code 0009 also appears with the title Validation Error when field-level validation rejects a request. See the note above.

The validation endpoint returns code 0143 with HTTP 413 when a request body exceeds the 100KB limit. The reason also appears in the top-level message field. The Tracer API returns code 0497 with HTTP 431 when the request headers are too large. It returns code 0484 with HTTP 404 for a path the service does not serve. It returns code 0485 with HTTP 405 for a method the path does not accept.

Date and time errors

---

code	title	message
0077	Invalid Date Format Error	The ‘initialDate’, ‘finalDate’, or both are in the incorrect format. Please use the ‘yyyy-mm-dd’ format and try again.
0083	Invalid Date Range Error	Both ‘initialDate’ and ‘finalDate’ fields are required and must be in the ‘yyyy-mm-dd’ format. Please provide valid dates and try again.

Pagination errors

---

code	title	message
0080	Pagination Limit Exceeded	The pagination limit exceeds the maximum allowed of %v items per page. Please verify the limit and try again.
0081	Invalid Sort Order	The ‘sort_order’ field must be ‘asc’ or ‘desc’. Please provide a valid sort order and try again.
0331	Pagination Limit Invalid	Pagination limit must be positive.
0332	Invalid Sort Column	Sort column not in allowed list.
0333	Invalid Cursor	Invalid or corrupted pagination cursor.
0334	Cursor With Sort Params	Cursor and sort parameters are mutually exclusive.

Metadata errors

---

These errors come from the metadata map on a validation request (POST /v1/validations).

code	title	message
0050	Metadata Key Length Exceeded	A metadata key exceeds the maximum allowed length of 64 characters. Please use a shorter key.
0335	Metadata Entries Exceeded	Metadata entries exceed maximum of 50.
0336	Metadata Key Invalid Chars	Metadata key contains invalid characters.

The API returns HTTP 400 for a metadata key longer than 64 characters, or for more than 50 metadata entries on one request.

CEL expression errors

---

You write rules as CEL (Common Expression Language) expressions. These errors appear during rule expression creation, update, or evaluation.

code	title	message
0340	Expression Syntax	Invalid CEL syntax.
0341	Expression Type	Expression must return boolean.
0342	Expression Cost Exceeded	Cost limit exceeded (cost computed and above threshold).
0343	Expression Evaluation	Runtime evaluation error.
0344	Expression Program	Program creation failed (compilation phase).
0345	Expression Cost Estimation	Failed to estimate expression cost.
0346	Amount Exceeds Precision	Amount exceeds safe precision for CEL float64 evaluation (max: ±2^53).
0351	Expression Not Modifiable	Expression cannot be modified for non-DRAFT rules.

Rule errors

---

code	title	message
0347	Rule Not Found	Rule not found by ID.
0348	Rule Name Already Exists	Rule name must be unique.
0349	Rule Invalid Status	Invalid rule status transition.
0350	Rule Evaluation Failed	Rule evaluation failed.
0352	Rule Nil Input	Rule input cannot be nil.
0353	Rule Name Required	Rule name is required.
0354	Rule Name Too Long	Rule name exceeds max length (255).
0355	Rule Expression Required	Rule expression is required.
0356	Rule Expression Too Long	Rule expression exceeds max length (5000).
0357	Rule Invalid Action	Action must be one of [ALLOW, DENY, REVIEW].
0358	Rule Invalid Scope	Scope must have at least one field set.
0359	Rule Description Too Long	Rule description exceeds max length (1000).
0360	Rule Scopes Too Many	Rule scopes exceed maximum (100).
0437	Rule Cache Not Ready	Rule cache is not ready.
0441	Rule Name Already Exists In Ctx	Rule name already exists in this context.

Limit errors

---

code	title	message
0362	Limit Not Found	Limit not found by ID.
0363	Limit Invalid Status Change	Invalid limit status transition.
0364	Limit Invalid Type	Invalid limit type.
0365	Limit Invalid Max Amount	MaxAmount must not be negative.
0366	Limit Invalid Asset	Asset must be 1 to 100 uppercase letters.
0367	Limit Invalid Scope	Scope validation failed.
0368	Limit Name Required	Limit name is required.
0369	Limit Name Too Long	Limit name exceeds max length.
0371	Limit Name Invalid Chars	Limit name contains invalid characters.
0372	Limit Description Invalid Chars	Limit description contains invalid characters.
0373	Limit Invalid ID	Limit ID is invalid or nil.
0378	Limit Check Failed	Limit check failed.
0379	Limit Nil Input	Limit input cannot be nil.
0380	Limit Immutable Field	Cannot modify immutable field (limitType, asset, resetTime).
0438	Limit Time Window Mismatch	ActiveTimeStart and activeTimeEnd must both be set or both be nil.
0440	Time Of Day Invalid Format	Invalid time of day format, expected HH:MM.
0442	Limit Name Already Exists	Limit name already exists.
0447	Limit Invalid Custom Start Format	Invalid customStartDate format, expected RFC3339.
0448	Limit Invalid Custom End Format	Invalid customEndDate format, expected RFC3339.
0449	Limit Custom Dates Required	CustomStartDate and customEndDate required for CUSTOM limitType.
0537	Limit Reset Time Not Allowed	ResetTime only allowed for DAILY, WEEKLY or MONTHLY limitType.
0538	Limit Reset Time Inside Window	ResetTime must not fall inside the active time window (it may equal activeTimeStart or activeTimeEnd).

Audit event errors

---

code	title	message
0381	Audit Event Not Found	Audit event not found.
0382	Invalid Audit Event Filters	Invalid audit event filter parameters.

Validation request errors

---

The transaction-validation endpoints (POST /v1/validations and the validation queries) return these errors.

code	title	message
0413	Validation Request IDRequired	RequestId is required.
0414	Validation Invalid Transaction Type	scheme (or transactionType) is required and must be 1 to 50 characters of A-Z, 0-9, _ or - after trimming and upper-casing
0415	Validation Amount Non Positive	Amount must be positive.
0416	Validation Asset Required	Asset is required.
0417	Validation Invalid Asset	Asset must be 1 to 100 uppercase letters.
0418	Validation Timestamp Required	Timestamp is required.
0419	Validation Timestamp Future	Timestamp cannot be in the future.
0420	Validation Account Required	Account is required.
0421	Validation Timestamp Past	Timestamp is too far in the past.
0422	Gateway Timeout	validation timeout
0423	Validation Segment IDRequired	SegmentId is required when segment is provided.
0424	Validation Portfolio IDRequired	PortfolioId is required when portfolio is provided.
0425	Validation Sub Type Too Long	SubType exceeds maximum length of 50 characters.
0426	Validation Invalid Account Type	Account.type must be at most 256 characters.
0427	Validation Invalid Account Status	Account.status must be at most 50 characters.
0428	Validation Invalid Merchant Category	Merchant.category must be 4-digit MCC code.
0429	Validation Invalid Merchant Country	Merchant.country must be ISO 3166-1 alpha-2.
0430	Validation Merchant IDRequired	Merchant.id is required when merchant is provided.
0431	Invalid Transaction Validation Filters	Invalid transaction validation filter parameters.
0432	Transaction Validation Not Found	Transaction validation record not found.
0433	Gateway Timeout	query timeout exceeded
0540	Scheme Alias Conflict	scheme and transactionType must carry the same value

The API returns codes 0422 and 0433 with HTTP 504 Gateway Timeout: 0422 when a validation evaluation exceeds its deadline, 0433 when a list-validations query does. For both codes, detail carries a generic value. The top-level message field carries the specific reason.

Rule and limit requests, and the list filters scheme and transaction_type, also return 0540 when the two names carry different values.

Reservation seam errors

---

Tracer returns these codes to the Midaz ledger on the gRPC reservation seam. The Tracer HTTP API does not return them. A Ledger API client receives Midaz codes instead. See the Midaz error list.

code	title	message
0476	Reservation Transaction IDReq	Reservation: transactionId is required.
0482	Reservation Not Found	Reservation: reservation not found.
0487	Reservation Tenant Required	Reservation: tenant id is required on the multi-tenant reservation surface.
0533	Reservation Already Settled	The reservation for this transaction was already settled and cannot be reserved again.
0534	Reservation Tenant Inactive	The tenant is not provisioned or not active for reservations.

Capacity and authentication errors

---

The instance returns HTTP 503 with a Retry-After header when it reaches its per-pod tenant worker cap. Clients should back off and retry. A Bearer token that parses but lacks the required sub claim returns HTTP 401.

Access Manager refusals include the AUT- codes below. AUT-0006 and AUT-0007 return HTTP 401, AUT-1020 returns 403, AUT-0033 returns 503 and AUT-1021 returns 504. With multi-tenancy on, Tracer returns TENANT_MANAGER_UNAVAILABLE (503) when the Tenant Manager is unavailable, and TENANT_MANAGER_TIMEOUT (504) when it does not answer in time.

code	title	message
0466	Tenant Capacity Reached	Tenant capacity reached; please retry shortly
0474	Unauthorized	Bearer token is missing the required ‘sub’ claim; identity cannot be attributed.
AUT-0006	Token Missing	A valid token must be provided in the request header. Please include a token and try again.
AUT-0007	Invalid Token	The provided token is expired, invalid or malformed. Please provide a valid token and try again.
AUT-1020	Permission Denied	the credential is not allowed to perform <resource>:<action> on this request
AUT-0033	Authorization Server Unavailable	The Access Manager did not decide this request. Please wait a moment and try again.
AUT-1021	Authorization Server Timeout	The Access Manager did not answer in time. Please try again.
TENANT_MANAGER_UNAVAILABLE	Tenant Manager Unavailable	tenant manager is unavailable; retry the request later
TENANT_MANAGER_TIMEOUT	Tenant Manager Timeout	tenant manager did not answer in time; retry the request

Readiness probe errors

---

The operational /readyz endpoint and the worker-supervisor lifecycle surface these codes. They appear in the error field of the /readyz JSON response (which carries the code only), not in /v1/* API responses. The title and message below describe each code for operator reference.

The /readyz cycle probes postgres, rule_cache, and streaming. streaming is advisory. It appears in the checks and metrics but never forces a 503.

code	title	message
0436	Rule Cache Warm Up Failed	Rule cache warm-up failed.
0459	Readyz Pg Connection Not Established	Postgres readyz: connection not established.
0460	Readyz Pg Connection Failed	Postgres readyz: connection failed.
0461	Readyz Pg Ping Failed	Postgres readyz: ping failed.
0462	Readyz Dependencies Unhealthy	/readyz aggregate: one or more dependencies unhealthy.
0463	Readyz Cache Not Ready	Rule_cache readyz: cache not ready.
0464	Readyz Cache Stale	Rule_cache readyz: cache data stale.
0465	Supervisor Shutting Down	Worker supervisor: shutting down, refusing to spawn new tenant workers.
0496	Readyz Streaming Unhealthy	Streaming readyz: producer unhealthy.