> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://www.rfc-editor.org/rfc/rfc9457) problem details object, served with the `application/problem+json` content type: ```json theme={null} { "type": "https://errors.lerian.studio/v1/", "title": "", "status": , "detail": "", "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`); authentication failures are the exception and use the literal string `Unauthenticated` (see the note below). * `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. Only present on `413 Payload Too Large` and `504 Gateway Timeout` responses; all other errors omit it. For server-side errors (HTTP 5xx), `title` and `detail` are sanitized to generic values so internal causes never leak. 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, `transactionType must be one of [CARD WIRE PIX CRYPTO]`. Examples: ```json Missing required field theme={null} { "type": "https://errors.lerian.studio/v1/0009", "title": "Validation Error", "status": 400, "detail": "name is a required field", "code": "0009" } ``` ```json Invalid expression type theme={null} { "type": "https://errors.lerian.studio/v1/0341", "title": "Expression Type", "status": 400, "detail": "Expression must return boolean.", "code": "0341", "entityType": "Rule" } ``` Two response families keep a legacy flat `{"code", "title", "message"}` shape instead of the problem details object, because they are emitted by middleware that runs before the API layer. 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 *** These errors can be returned by any Tracer API endpoint. | `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. | | 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. Code `0143` is returned with HTTP `413` when a request body exceeds the 100KB limit on the validation and reservation endpoints; the reason also appears in the top-level `message` field. Code `0497` is returned with HTTP `431` when the request headers are too large. ## 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. | ## CEL expression errors *** Rules are written as CEL (Common Expression Language) expressions. These errors are raised when a rule expression is created, updated, or evaluated. | `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 be positive. | | 0366 | Limit Invalid Currency | Currency must be valid ISO 4217. | | 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. | | 0370 | Limit Already Deleted | Limit is already in DELETED state. | | 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, currency). | | 0438 | Limit Time Window Mismatch | ActiveTimeStart and activeTimeEnd must both be set or both be nil. | | 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. | ## 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 *** These errors are returned by the transaction-validation endpoints (`POST /validations` and the validation queries). | `code` | `title` | `message` | | :----- | :------------------------------------- | :--------------------------------------------------- | | 0413 | Validation Request IDRequired | RequestId is required. | | 0414 | Validation Invalid Transaction Type | Invalid transactionType. | | 0415 | Validation Amount Non Positive | Amount must be positive. | | 0416 | Validation Currency Required | Currency is required. | | 0417 | Validation Invalid Currency | Currency must be valid ISO 4217. | | 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 checking, savings, or credit. | | 0427 | Validation Invalid Account Status | Account.status must be active, suspended, or closed. | | 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 | Codes `0422` and `0433` are returned with HTTP `504 Gateway Timeout` — `0422` when a validation evaluation exceeds its deadline, `0433` when a list-validations query does. As with all 5xx responses, `detail` is sanitized; the specific reason is carried in the top-level `message` field. ## Reservation errors *** These errors are returned by the usage-reservation endpoints (`/reservations`), the two-phase reserve / confirm / release surface. Reservation requests can also return the general and validation-request errors listed above. | `code` | `title` | `message` | | :----- | :---------------------------- | :-------------------------------------------------------------------------- | | 0476 | Reservation Transaction IDReq | Reservation: transactionId is required. | | 0480 | Reservation Invalid Status | Reservation: status must be one of RESERVED, CONFIRMED, RELEASED, EXPIRED. | | 0482 | Reservation Not Found | Reservation: reservation not found. | | 0483 | Reservation Already Terminal | Reservation: reservation is already in a terminal state. | | 0487 | Reservation Tenant Required | Reservation: tenant id is required on the multi-tenant reservation surface. | ## Multi-tenant 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 is rejected with HTTP 401. | `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. | ## 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` | | :----- | :----------------------------- | :----------------------------------------------------------------------------------------- | | 0451 | MTConfig Required | Multi-tenant config: cfg is required. | | 0452 | MTLogger Required | Multi-tenant config: logger is required. | | 0453 | MTURLRequired | MULTI\_TENANT\_URL must be set when MULTI\_TENANT\_ENABLED=true. | | 0454 | MTURLInvalid | MULTI\_TENANT\_URL must be a valid absolute URL with scheme and host. | | 0455 | MTService APIKey Required | MULTI\_TENANT\_SERVICE\_API\_KEY must be set when MULTI\_TENANT\_ENABLED=true. | | 0456 | MTRedis Host Required | MULTI\_TENANT\_REDIS\_HOST must be set when MULTI\_TENANT\_ENABLED=true. | | 0457 | MTPlugin Auth Required | MULTI\_TENANT\_ENABLED=true requires PLUGIN\_AUTH\_ENABLED=true. | | 0458 | MTAPIKey Only Validation Confl | MULTI\_TENANT\_ENABLED=true is incompatible with API\_KEY\_ENABLED\_ONLY\_VALIDATION=true. | ## Readiness probe errors *** These codes are surfaced by the operational `/readyz` endpoint and by the worker-supervisor lifecycle. 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 five dependencies: `postgres` and `rule_cache` always; `redis` and `tenant_manager` only in multi-tenant mode (skipped otherwise); `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. | | 0493 | Readyz Redis Connection Not Established | Redis readyz: connection not established. | | 0494 | Readyz Redis Ping Failed | Redis readyz: ping failed. | | 0495 | Readyz Tenant Manager Unavailable | Tenant\_manager readyz: service unavailable. | | 0496 | Readyz Streaming Unhealthy | Streaming readyz: producer unhealthy. |