Reporter error list

Reporter returns consistent, structured error responses. Look up error codes, HTTP statuses, and remediation steps to resolve API failures quickly.

Error format

Reporter returns errors as RFC 9457 problem details with the application/problem+json media type:

JSON

{
  "type": "https://errors.lerian.studio/v1/RPT-0012",
  "title": "Bad Request",
  "status": 400,
  "detail": "The specified templateID is not a valid UUID. Please check the value passed.",
  "code": "RPT-0012"
}

Field definitions

• type – A URI that identifies the error in the Lerian error catalog. Built as https://errors.lerian.studio/v1/<code>.
• title – The HTTP status text (for example, Bad Request).
• status – The HTTP status code.
• detail – Detailed guidance to help you resolve the error. For 5xx responses, the detail is always sanitized to internal error so no internal cause leaks; use code to branch programmatically.
• code – A stable, unique identifier for the error (RPT-NNNN). Useful for programmatic handling and support requests.
• errors – Optional list of per-field validation details, each with a message and a location.

Some messages contain placeholders such as %v or %s — Reporter replaces them with the specific values from your request.

Reporter errors

---

The following errors can occur when interacting with the Reporter endpoints. Refer to the tables below for the possible error codes, what they mean, and how to resolve them.

400 — Validation errors

---

code	Description	detail
RPT-0001	Missing required fields	One or more required fields are missing. Please ensure all required fields are included.
RPT-0002	Invalid file format	The uploaded file must be a .tpl file. Other formats are not supported.
RPT-0003	Invalid output format	The outputFormat field must be one of: html, csv, or xml.
RPT-0004	Invalid header	One or more header values are missing or incorrectly formatted. Please verify required headers %v.
RPT-0005	Invalid File Uploaded	The file you submitted is invalid. Please check the uploaded file with error: %v
RPT-0006	Error File Empty	The file you submitted is empty. Please check the uploaded file.
RPT-0007	Error File Content Invalid	The file content is invalid because is not %s. Please check the uploaded file.
RPT-0008	Invalid Map Fields	The field on template file is invalid. Invalid field %s on %s.
RPT-0009	Invalid Path Parameter	Path parameters is in an incorrect format. Please check the following parameter %v and ensure they meet the required format before trying again.
RPT-0010	Update Output format without template File	Can not update output format without passing template file. Please check information passed and try again.
RPT-0012	Invalid templateID	The specified templateID is not a valid UUID. Please check the value passed.
RPT-0013	Invalid ledgerID	The specified ledgerID inside ledger ID list is not a valid UUID. Please check the value passed %v.
RPT-0014	Missing required fields	The fields mapped on template file are missing in the table schema or may be empty. Please check the fields passed: ‘%v’.
RPT-0015	Unexpected Fields in the Request	The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object.
RPT-0016	Missing Fields in Request	Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request.
RPT-0017	Bad Request	The server could not understand the request due to malformed syntax. Please check the listed fields and try again.
RPT-0019	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.
RPT-0023	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.
RPT-0024	Pagination Limit Exceeded	The pagination limit exceeds the maximum allowed of %v items per page. Please verify the limit and try again.
RPT-0025	Invalid Sort Order	The ‘sort_order’ field must be ‘asc’ or ‘desc’. Please provide a valid sort order and try again.
RPT-0026	Metadata Key Length Exceeded	The metadata key %v exceeds the maximum allowed length of %v characters. Please use a shorter key.
RPT-0027	Metadata Value Length Exceeded	The metadata value %v exceeds the maximum allowed length of %v characters. Please use a shorter value.
RPT-0028	Invalid Metadata Nesting	The metadata object cannot contain nested values. Please ensure that the value %v is not nested and try again.
RPT-0030	Missing Schema Table	The schema table %v is missing for data source ‘%v’. Please check the information passed.
RPT-0031	Missing Data Source Table	The data source %v is missing. Please check the value passed.
RPT-0032	Script Tag Detected	The template file contains a script tag and is not allowed. Please check the template file and try again.
RPT-0035	Ambiguous Schema Reference	The table ‘%v’ exists in multiple schemas: %v. Please use explicit schema syntax: database:schema.table
RPT-0036	Schema Not Found	The schema ‘%v’ was not found in database ‘%v’. Please verify the schema name.
RPT-0037	Table Not Found in Schema	The table ‘%v’ was not found in schema ‘%v’ of database ‘%v’. Please verify the table name and schema.
RPT-0038	Database Not Registered	The database ‘%v’ is not registered. Please verify the datasource configuration.
RPT-0041	Bucket Required	The storage bucket name is required. Please check the storage configuration.
RPT-0042	Object Key Required	The object key is required for the storage operation.
RPT-0044	TTL Not Supported	TTL parameter is not supported in S3 mode. Use bucket lifecycle policies instead.
RPT-0046	Invalid Deadline Type	The ‘type’ field must be ‘regulatory’ or ‘custom’. Please provide a valid deadline type and try again.
RPT-0047	Invalid Deadline Frequency	The ‘frequency’ field must be one of: ‘once’, ‘daily’, ‘weekly’, ‘monthly’, ‘semiannual’, ‘annual’. Please provide a valid frequency and try again.
RPT-0048	Invalid Deadline Color	The ‘color’ field must be a valid hex color code (e.g., ‘#FF5733’). Please provide a valid color and try again.
RPT-0050	Months of Year Not Applicable	The ‘monthsOfYear’ field is not applicable for frequency ‘%v’. It can only be used with ‘semiannual’ or ‘annual’ frequencies.
RPT-0052	Months of Year Required	The ‘monthsOfYear’ field is required for frequency ‘%v’. Please specify which months of the year the deadline should recur on.
RPT-0054	Months of Year Out of Range	Each value in ‘monthsOfYear’ must be between 1 and 12. Received invalid value: %v.
RPT-0055	Due Date in the Past	The ‘dueDate’ must be today or a future date. Please provide a date that is not in the past.
RPT-0056	Months of Year Count Mismatch	The number of months in ‘monthsOfYear’ does not match the ‘%v’ frequency. ‘semiannual’ requires exactly 2 months and ‘annual’ requires exactly 1 month.
RPT-0059	Schema Validation Failed	The schema validation failed. Please verify the fields against the data source schema.
RPT-0062	Invalid UTF-8 Encoding	The ‘%v’ field contains invalid UTF-8 byte sequences. Please provide valid UTF-8 text and try again.

The RPT-0003 message lists html, csv, and xml, but the API accepts five output formats: HTML, PDF, CSV, XML, and TXT. See Upload template.

404 — Not found

---

code	Description	detail
RPT-0011	Entity Not Found	No %v entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage.
RPT-0020	Invalid Date Format Error	The ‘initialDate’, ‘finalDate’, or both are in the incorrect format. Please use the ‘yyyy-mm-dd’ format and try again.
RPT-0021	Invalid Final Date Error	The ‘finalDate’ cannot be earlier than the ‘initialDate’. Please verify the dates and try again.
RPT-0022	Date Range Exceeds Limit Error	The range between ‘initialDate’ and ‘finalDate’ exceeds the permitted limit of %v months. Please adjust the dates and try again.
RPT-0043	Object Not Found	The requested object was not found in storage.
RPT-0057	Data Source Not Found	The requested data source was not found. Please verify the data source ID.

409 — Conflicts

---

code	Description	detail
RPT-0039	Duplicate Request In Flight	A duplicate request is currently being processed. Please wait and try again.
RPT-0040	Idempotency Conflict	A request with this idempotency key has already been processed.
RPT-0045	Duplicate Deadline	A deadline with the same name, type, due date, and frequency already exists. Please use different values or update the existing deadline.

422 — Unprocessable

---

code	Description	detail
RPT-0029	Report status not Finished	The Report is not ready to download. Report is processing yet.

500 — Server errors

---

code	Description	detail
RPT-0018	Internal Server Error	internal error

Every unexpected failure during synchronous endpoint handling surfaces as HTTP 500 with code: RPT-0018 and a sanitized internal error detail — internal causes never leak into the response body. Asynchronous worker and report-generation failures instead follow the report statuses and metadata described below; they are not returned to the original request as HTTP 500.

Report-generation errors (asynchronous)

---

Report generation runs asynchronously in the worker. A failed data-extraction section is not returned to the original HTTP request: the report ends with status Error when all sections fail or Partial when some fail. In either case, metadata.error_code is RPT-0060; metadata.sections is keyed by database name, and each failed entry contains only its classified error_code (RPT-0018 for an untyped failure). Other worker failures end with status Error and a safe non-RPT metadata.error_code of report_generation_failed, report_generation_timeout, or report_generation_canceled; they have no sections map and do not retain the underlying RPT code.

code	Description	Meaning
RPT-0033	Encryption data error	Failed to decrypt CRM data during extraction.
RPT-0034	Communication Error with SeaweedFS	Error communicating with the file storage to download or upload a file. Please try again.
RPT-0058	Data Source Unavailable	The data source is currently unavailable. Results may be incomplete.
RPT-0060	Extraction Job Failed	The extraction job failed. Please try again later or contact support.
RPT-0061	Template Rendering Failed	The template could not be rendered with the provided data. This is a permanent error and will not succeed on retry.
RPT-0063	CRM Hash Key Not Configured	CRM hash key not configured.
RPT-0064	CRM Encrypt Key Not Configured	CRM encrypt key not configured.
RPT-0065	Record Decryption Failed	Record decryption failed.
RPT-0066	Cipher Init Failed	Cipher initialization failed.
RPT-0067	Invalid Extracted Data	The extracted data is invalid.
RPT-0068	Unexpected Collection Result	The data collection returned an unexpected result.
RPT-0069	Data Source Not Found	The data source referenced by the report was not found.
RPT-0070	Data Source Unavailable	The data source was unavailable during extraction.