> ## 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.
# 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 JSON theme={null}
{
"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/`.
* **`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](/en/reference/reporter/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. |