Tracer error list

The format is as follows:

{
   "code":"<error_code>",
   "title":"<error_title>",
   "message":"<error_message>"
}

Field definitions

code: A unique, stable identifier for the error (format: TRC-XXXX).
title: A brief summary of the issue.
message: Detailed guidance for resolving the error.

Field-level error details For issues specific to individual fields, a fields object provides additional context. Examples:

{
   "code":"TRC-0106",
   "title":"Missing Required Field",
   "message":"The name field is required. Please provide a name for the rule and try again.",
   "fields": {
      "name": "name is a required field"
   }
}

Authentication failures return "code": "Unauthenticated" (not a TRC code) with HTTP 401. This is a stable, well-known identifier rather than a TRC code, so clients should match on the literal string.

General errors

These errors apply to all Tracer API endpoints.

`code`	`title`	`message`
TRC-0001	Validation Error	Field validation failed. Please verify the provided data and try again.
TRC-0002	At Least One Field Required	At least one field must be provided for update. Please include at least one field and try again.
TRC-0003	Invalid Request Body	The request body is invalid or malformed. Please verify the JSON format and try again.
TRC-0004	Internal Server Error	An unexpected error occurred. Please try again later or contact support if the issue persists.
TRC-0005	Invalid Calculation Field Type	The calculation field type is invalid. Please verify the field type and try again.
TRC-0006	Invalid Query Parameters	One or more query parameters are invalid. Please verify the parameters and try again.
TRC-0007	Invalid Path Parameter	The provided ID is not a valid UUID format. Please verify the ID and try again.
TRC-0010	Parent ID Not Found	The referenced parent resource ID does not exist. Please verify the ID and try again.
TRC-0011	Payload Too Large	The request payload exceeds the maximum size limit of 100KB. Please reduce the payload size and try again.
TRC-0012	Service Unavailable	The service is temporarily unavailable or the request was cancelled. Please try again later.

Date and time errors

`code`	`title`	`message`
TRC-0020	Invalid Date Format	The date must be in RFC3339 format with timezone (e.g., 2026-01-28T10:30:00Z). Date-only format is not accepted.
TRC-0021	Invalid Final Date	The final date is invalid. Please provide a valid date in RFC3339 format.
TRC-0022	Date Range Exceeds Limit	The date range exceeds the maximum allowed window. Please reduce the date range and try again.
TRC-0023	Invalid Date Range	The date range is invalid (start date must be before end date). Please verify the dates and try again.

Pagination errors

`code`	`title`	`message`
TRC-0040	Limit Exceeds Maximum	The limit parameter exceeds the maximum allowed value. Please reduce the limit and try again.
TRC-0041	Limit Below Minimum	The limit parameter must be at least 1. Please provide a valid limit and try again.
TRC-0042	Invalid Sort Order	Sort order must be ASC or DESC. Please provide a valid value.
TRC-0043	Invalid Sort Column	The specified sort column is not supported. Please check the allowed fields.
TRC-0044	Invalid Pagination Cursor	The provided pagination cursor is invalid or expired. Please start a new query without a cursor.
TRC-0045	Sort Parameters Locked	Cannot change sort_by or sort_order when using a pagination cursor. Please start a new query to change sort parameters.

Metadata errors

`code`	`title`	`message`
TRC-0060	Metadata Key Too Long	The metadata key exceeds the maximum length of 64 characters. Please reduce the key size.
TRC-0061	Metadata Value Too Long	The metadata value exceeds the maximum allowed length. Please reduce the value size.
TRC-0062	Invalid Metadata Nesting	The metadata contains nested objects, which are not allowed. Use a flat key/value structure.
TRC-0063	Metadata Exceeds Maximum Entries	The metadata exceeds the maximum of 50 entries. Please reduce the number of entries.
TRC-0064	Invalid Metadata Key	The metadata key contains invalid characters. Only alphanumeric characters and underscore are allowed.

Decision and CEL expression errors

`code`	`title`	`message`
TRC-0080	Invalid Decision	The decision value must be one of ALLOW, DENY, or REVIEW. Please provide a valid decision.
TRC-0081	Reason Required	A reason is required for this decision. Please provide a reason and try again.
TRC-0082	Invalid Default Decision	The default decision value must be one of ALLOW, DENY, or REVIEW. Please verify the service configuration.
TRC-0083	Expression Syntax Error	The CEL expression contains a syntax error. Please verify the expression syntax and try again.
TRC-0084	Expression Type Error	The CEL expression must evaluate to a boolean value. Please modify the expression to return true or false.
TRC-0085	Expression Cost Exceeded	The CEL expression computational cost exceeds the allowed limit. Please simplify the expression.
TRC-0086	Expression Evaluation Error	The CEL expression failed at runtime. Please verify the expression and the available context variables.
TRC-0087	Expression Compilation Failed	The CEL expression could not be compiled. Please verify the expression syntax and types.
TRC-0088	Expression Cost Estimation Failed	The CEL expression cost could not be estimated. Please simplify the expression and try again.
TRC-0089	Amount Exceeds CEL Precision	The amount exceeds the safe precision for CEL evaluation (maximum ±2^53). Please reduce the amount.

Rule errors

`code`	`title`	`message`
TRC-0100	Rule Not Found	The requested rule does not exist. Please verify the rule ID and try again.
TRC-0101	Rule Name Conflict	A rule with this name already exists. Please choose a different name and try again.
TRC-0102	Invalid Status Transition	The requested status transition is not allowed. Please check the current rule status and valid transitions.
TRC-0103	Internal Server Error	Rule evaluation failed. Please try again or contact support.
TRC-0104	Expression Not Modifiable	The expression can only be modified when the rule is in DRAFT status. Please move the rule back to DRAFT first.
TRC-0105	Invalid Rule Input	The rule input is missing or null. Please provide a complete rule body and try again.
TRC-0106	Missing Required Field	The name field is required. Please provide a name for the rule and try again.
TRC-0107	Name Too Long	The name exceeds the maximum length of 255 characters. Please reduce the name size.
TRC-0108	Missing Required Field	The expression field is required. Please provide a CEL expression for the rule and try again.
TRC-0109	Expression Too Long	The expression exceeds the maximum length of 5000 characters. Please reduce the expression size.
TRC-0110	Invalid Action	The action must be one of ALLOW, DENY, or REVIEW. Please provide a valid action.
TRC-0111	Invalid Scope	Each scope must have at least one field set. Please provide at least one field in the scope.
TRC-0112	Description Too Long	The description exceeds the maximum length of 1000 characters. Please reduce the description size.
TRC-0113	Scopes Exceed Maximum	The scopes exceed the maximum of 100 entries. Please reduce the number of scopes.
TRC-0114	Status Transition Not Allowed	The requested status transition is not permitted from the current rule status. Please check the valid lifecycle transitions.

Limit errors

`code`	`title`	`message`
TRC-0120	Limit Not Found	The requested limit does not exist. Please verify the limit ID and try again.
TRC-0121	Invalid Status Transition	The requested status transition is not allowed. Please check the current limit status and valid transitions.
TRC-0122	Invalid Limit Type	The limitType must be one of DAILY, WEEKLY, MONTHLY, CUSTOM, or PER_TRANSACTION. Please provide a valid limit type.
TRC-0123	Invalid Amount	The maxAmount must be a positive decimal string. Please provide a valid decimal amount.
TRC-0124	Invalid Currency Code	The currency must be a valid 3-letter ISO 4217 code (e.g., BRL, USD). Please provide a valid currency code.
TRC-0125	Missing Required Field	At least one scope is required for limits. Please provide at least one scope and try again.
TRC-0126	Missing Required Field	The name field is required. Please provide a name for the limit and try again.
TRC-0127	Name Too Long	The limit name exceeds the maximum allowed length. Please reduce the name size.
TRC-0128	Cannot Modify Deleted Limit	The limit has been deleted and cannot be modified. Please create a new limit if needed.
TRC-0129	Invalid Name	The name contains invalid characters. Please use only allowed characters.
TRC-0130	Invalid Description	The description contains invalid characters. Please use only allowed characters.
TRC-0131	Immutable Field	The limitType and currency fields cannot be modified after creation. Please create a new limit if you need different values.
TRC-0132	Description Too Long	The limit description exceeds the maximum allowed length. Please reduce the description size.
TRC-0133	Invalid Status Filter	The status filter value is invalid. Please use one of DRAFT, ACTIVE, INACTIVE, or DELETED.
TRC-0134	Invalid Limit Type Filter	The limit_type filter value is invalid. Please use one of DAILY, WEEKLY, MONTHLY, CUSTOM, or PER_TRANSACTION.
TRC-0135	Inconsistent Deletion State	The limit’s deletion state is inconsistent (DeletedAt set only when status is DELETED). Please contact support.
TRC-0136	Internal Server Error	Limit check failed. Please try again or contact support.
TRC-0137	Invalid Limit Input	The limit input is missing or null. Please provide a complete limit body and try again.
TRC-0138	Immutable Field	The limitType and currency fields cannot be modified after creation. Please create a new limit if you need different values.

Limit time window and custom period errors

`code`	`title`	`message`
TRC-0300	Inconsistent Time Window	activeTimeStart and activeTimeEnd must both be set or both be unset. Please provide both values or neither.
TRC-0301	Zero-Width Time Window	activeTimeStart and activeTimeEnd cannot be the same value. Please provide a non-zero time window.
TRC-0302	Invalid Time Format	The time of day must be in HH:MM format (e.g., 09:00). Please verify the format and try again.
TRC-0303	Rule Name Conflict in Context	A rule with this name already exists in this context (segment scope). Please choose a different name.
TRC-0304	Limit Name Conflict	A limit with this name already exists. Please choose a different name.
TRC-0305	Custom Dates Not Allowed	customStartDate and customEndDate are only allowed when limitType is CUSTOM. Please remove these fields or change the limit type.
TRC-0306	Unknown Limit Type	The limit type is unknown. Please provide one of DAILY, WEEKLY, MONTHLY, CUSTOM, or PER_TRANSACTION.
TRC-0307	Custom Period Too Long	The custom period cannot exceed 5 years. Please reduce the period range.
TRC-0308	Custom Period Expired	The custom period end date must be in the future. Please provide a future end date.
TRC-0309	Invalid Custom Start Date	The customStartDate must be in RFC3339 format. Please verify the format and try again.
TRC-0310	Invalid Custom End Date	The customEndDate must be in RFC3339 format. Please verify the format and try again.
TRC-0311	Custom Dates Required	customStartDate and customEndDate are required when limitType is CUSTOM. Please provide both dates.
TRC-0312	Invalid Custom Date Order	customStartDate must be before customEndDate. Please verify the date order.

Audit event errors

`code`	`title`	`message`
TRC-0140	Audit Event Not Found	The requested audit event does not exist. Please verify the event ID and try again.
TRC-0141	Invalid Audit Event Filters	One or more audit event filters are invalid. Please verify the filter values and try again.
TRC-0142	Invalid Audit Event Type	The event_type filter must be a valid audit event type. Please verify the allowed values.
TRC-0143	Invalid Audit Action	The action filter must be one of VALIDATE, CREATE, UPDATE, DELETE, ACTIVATE, DEACTIVATE, or DRAFT. Please verify the action.
TRC-0144	Invalid Audit Result	The result filter must be one of SUCCESS, FAILED, ALLOW, DENY, or REVIEW. Please verify the result.
TRC-0145	Missing Resource ID	The resource ID is required for this audit query. Please provide a resource ID.
TRC-0146	Invalid Resource Type	The resource_type must be one of transaction, rule, or limit. Please provide a valid resource type.
TRC-0147	Missing Actor ID	The actor ID is required for this audit query. Please provide an actor ID.
TRC-0148	Invalid Actor Type	The actor_type must be ‘user’ or ‘system’. Please provide a valid actor type.

Usage counter errors

These errors come from the usage counter subsystem that backs spending-limit enforcement. Most are surfaced as 500 Internal Server Error responses with the corresponding TRC code.

`code`	`title`	`message`
TRC-0160	Usage Counter Overflow	The usage counter would overflow. Please contact support.
TRC-0161	Internal Server Error	Usage counter limitID is required (internal invariant). Please contact support.
TRC-0162	Internal Server Error	Usage counter scopeKey is required (internal invariant). Please contact support.
TRC-0163	Internal Server Error	Usage counter periodKey is required (internal invariant). Please contact support.
TRC-0164	Internal Server Error	Usage counter currentUsage must be non-negative (internal invariant). Please contact support.
TRC-0165	Internal Server Error	Increment amount must be non-negative (internal invariant). Please contact support.
TRC-0166	Usage Counter Not Found	The usage counter for this limit and scope does not exist. Please verify the limit configuration.
TRC-0167	Limit Exceeded	The transaction would exceed the limit maximum. The validation will be denied.
TRC-0168	Internal Server Error	Decrement amount must be non-negative (internal invariant). Please contact support.

Limit check errors

These errors occur during limit enforcement on validation requests. Most are internal invariants; user-facing variants typically surface via Validation Request errors (TRC-0220 series).

`code`	`title`	`message`
TRC-0180	Invalid Amount	The transaction amount must be positive for limit checks. Please provide a valid amount.
TRC-0181	Invalid Currency	The currency must be a valid ISO 4217 code for limit checks. Please verify the currency code.
TRC-0183	Unknown Limit Type	The limit type is not recognized for period key calculation. Please contact support.
TRC-0184	Invalid Timestamp	The timestamp must not be zero for limit checks. Please provide a valid timestamp.
TRC-0185	Internal Server Error	Limit check input is missing or null (internal invariant). Please contact support.
TRC-0186	Missing Account ID	The account ID is required for limit checks. Please provide an accountId.
TRC-0187	Invalid Transaction Type	The transactionType must be one of CARD, WIRE, PIX, or CRYPTO for limit checks.
TRC-0188	SubType Too Long	The subType exceeds the maximum length of 50 characters for limit checks.
TRC-0189	Invalid Segment ID	The segmentId cannot be the zero UUID. Please provide a valid UUID.
TRC-0190	Invalid Portfolio ID	The portfolioId cannot be the zero UUID. Please provide a valid UUID.
TRC-0191	Invalid Merchant ID	The merchantId cannot be the zero UUID. Please provide a valid UUID.

Service initialization errors

These codes are surfaced during service startup or by constructor validation. They are not returned by client requests but may appear in startup logs.

`code`	`title`	`message`
TRC-0200	Internal Server Error	Limit checker initialization failed: limit repository is required. Please contact support.
TRC-0201	Internal Server Error	Limit checker initialization failed: usage counter repository is required. Please contact support.
TRC-0202	Internal Server Error	Limit checker initialization failed: clock dependency is required. Please contact support.

Validation request errors

`code`	`title`	`message`
TRC-0220	Missing Required Field	The requestId field is required. Please provide a unique UUID for the request.
TRC-0221	Invalid Transaction Type	The transactionType must be one of CARD, WIRE, PIX, or CRYPTO. Please provide a valid transaction type.
TRC-0222	Invalid Amount	The amount must be a positive decimal value (e.g., “1500.00”). Please provide a valid amount.
TRC-0223	Missing Required Field	The currency field is required. Please provide a valid ISO 4217 currency code.
TRC-0224	Invalid Currency	The currency must be a valid uppercase ISO 4217 code (e.g., BRL, USD). Lowercase codes are not accepted.
TRC-0225	Missing Required Field	The transactionTimestamp field is required. Please provide a timestamp in RFC3339 format.
TRC-0226	Future Timestamp Not Allowed	The transactionTimestamp cannot be in the future. Please provide a valid timestamp.
TRC-0227	Missing Required Field	The account field is required. Please provide account context for the validation.
TRC-0228	Past Timestamp Not Allowed	The transactionTimestamp is too far in the past. Please provide a more recent timestamp.
TRC-0229	Gateway Timeout	The validation processing exceeded the 80ms budget. Please try again or contact support if the issue persists.
TRC-0230	Missing Required Field	The segment.id field is required when the segment object is provided. Please provide the segment ID.
TRC-0231	Missing Required Field	The portfolio.id field is required when the portfolio object is provided. Please provide the portfolio ID.
TRC-0232	SubType Too Long	The subType field exceeds the maximum length of 50 characters. Please reduce the size.
TRC-0233	Invalid Account Type	The account.type must be one of checking, savings, or credit. Please provide a valid type.
TRC-0234	Invalid Account Status	The account.status must be one of active, suspended, or closed. Please provide a valid status.
TRC-0235	Invalid Merchant Category	The merchant.category must be a 4-digit MCC code. Please provide a valid category.
TRC-0236	Invalid Merchant Country	The merchant.country must be an ISO 3166-1 alpha-2 code (e.g., BR, US). Please provide a valid country code.
TRC-0237	Missing Required Field	The merchant.id field is required when the merchant object is provided. Please provide the merchant ID.

Transaction validation errors

`code`	`title`	`message`
TRC-0250	Invalid Filters	One or more transaction validation filters are invalid. Please verify the filter values and try again.
TRC-0251	Transaction Validation Not Found	The requested transaction validation does not exist. Please verify the validation ID and try again.
TRC-0252	Gateway Timeout	The query exceeded the allowed timeout. Please refine the filters to reduce the query scope.
TRC-0270	Internal Server Error	Transaction validation ID is required (internal invariant). Please contact support.
TRC-0271	Internal Server Error	Transaction validation createdAt is required (internal invariant). Please contact support.

Cache errors

`code`	`title`	`message`
TRC-0280	Cache Warm-Up Failed	The rule cache failed to initialize at startup. The service may operate in degraded mode.
TRC-0281	Cache Not Ready	The rule cache is not ready to serve traffic. Please retry the request after a brief delay.

Readiness probe errors

These codes are surfaced by the operational /readyz endpoint and by the worker supervisor lifecycle. They appear in the JSON error field of /readyz responses, not in /v1/* API responses. Operators rely on the literal code (not the message) for dashboard alerting.

`code`	`title`	`message`
TRC-0328	Database Connection Not Established	The PostgreSQL connection has not been established. Wait for service startup to complete.
TRC-0329	Database Connection Failed	The PostgreSQL connection attempt failed. Check database availability and credentials.
TRC-0330	Database Ping Failed	The PostgreSQL ping probe failed. The database may be unreachable or unresponsive.
TRC-0331	Dependencies Unhealthy	One or more dependencies reported unhealthy on the readiness probe. The service is returning HTTP 503.
TRC-0332	Rule Cache Not Ready	The rule cache is not ready to serve readiness traffic. The service will become ready after warm-up completes.
TRC-0333	Rule Cache Stale	The rule cache data is stale beyond the configured threshold. Background sync may be lagging.
TRC-0334	Worker Supervisor Shutting Down	The worker supervisor is shutting down and refused to spawn new tenant workers. New tenants will be rejected with HTTP 503 until the next instance is healthy.

Multi-tenant bootstrap errors

These codes surface only at service startup when MULTI_TENANT_ENABLED=true and a required configuration is missing or incompatible. They appear in startup logs (and prevent the service from starting) — they never reach /v1/* API consumers.

`code`	`title`	`message`
TRC-0320	Multi-Tenant Config Required	Multi-tenant configuration is required when `MULTI_TENANT_ENABLED=true`. Please verify the service configuration.
TRC-0321	Multi-Tenant Logger Required	Multi-tenant initialization requires a logger instance. This is a service-internal error; contact support.
TRC-0322	Multi-Tenant URL Required	`MULTI_TENANT_URL` must be set when `MULTI_TENANT_ENABLED=true`. Set the Tenant Manager URL and restart the service.
TRC-0323	Multi-Tenant URL Invalid	`MULTI_TENANT_URL` must be a valid absolute URL with scheme and host (e.g., `https://tenant-manager.example.com`).
TRC-0324	Multi-Tenant Service API Key Required	`MULTI_TENANT_SERVICE_API_KEY` must be set when `MULTI_TENANT_ENABLED=true`. Provide the API key for calling the Tenant Manager.
TRC-0325	Multi-Tenant Redis Host Required	`MULTI_TENANT_REDIS_HOST` must be set when `MULTI_TENANT_ENABLED=true`. The shared Redis Pub/Sub host is required for tenant lifecycle events.
TRC-0326	Plugin Auth Required for Multi-Tenant	`MULTI_TENANT_ENABLED=true` requires `PLUGIN_AUTH_ENABLED=true`. Enable plugin authentication and restart the service.
TRC-0327	API-Key-Only Validation Incompatible with Multi-Tenant	`MULTI_TENANT_ENABLED=true` is incompatible with `API_KEY_ENABLED_ONLY_VALIDATION=true`. Choose one mode and restart the service.

Multi-tenant runtime errors

`code`	`title`	`message`
TRC-0335	Tenant Capacity Reached	The instance has reached its per-pod tenant cap and cannot serve this tenant right now. The response includes a `Retry-After` header — clients should back off and retry. The cap auto-resets as the LRU pool evicts cold tenants.

When the JWT is missing, malformed, expired, or has no tenantId claim, multi-tenant deployments return HTTP 401 with "code": "Unauthenticated" — the same code emitted for a missing API key in single-tenant mode. No separate TRC code is emitted for tenant authentication failures.

Documentation Index

​General errors

​Date and time errors

​Pagination errors

​Metadata errors

​Decision and CEL expression errors

​Rule errors

​Limit errors

​Limit time window and custom period errors

​Audit event errors

​Usage counter errors

​Limit check errors

​Service initialization errors

​Validation request errors

​Transaction validation errors

​Cache errors

​Readiness probe errors

​Multi-tenant bootstrap errors

​Multi-tenant runtime errors

General errors

Date and time errors

Pagination errors

Metadata errors

Decision and CEL expression errors

Rule errors

Limit errors

Limit time window and custom period errors

Audit event errors

Usage counter errors

Limit check errors

Service initialization errors

Validation request errors

Transaction validation errors

Cache errors

Readiness probe errors

Multi-tenant bootstrap errors

Multi-tenant runtime errors