---
title: Error Handling & Best Practices
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/custom-metadata-reference
---

## Error Handling & Best Practices

### Error Handling


| Error Code | Meaning |
|------------|---------|
| `METADATA_PROFILE_NOT_FOUND` | Profile ID does not exist |
| `METADATA_NOT_FOUND` | Metadata instance ID does not exist |
| `METADATA_ALREADY_EXISTS` | Metadata already exists for this profile+object combination |
| `INVALID_METADATA_DATA` | XML data does not conform to the profile's XSD |
| `INVALID_METADATA_PROFILE_SCHEMA` | XSD schema is invalid |
| `INVALID_OBJECT_ID` | The object ID does not exist or access denied |
| `INCOMPATIBLE_METADATA_PROFILE_OBJECT_TYPE` | Profile objectType does not match the objectType parameter |
| `INVALID_METADATA_VERSION` | Optimistic locking version mismatch (concurrent update) |
| `XSLT_VALIDATION_ERROR` | XSLT transformation produced invalid output |
| `METADATA_UNABLE_TO_TRANSFORM` | XSD change is incompatible with existing metadata data |
| `METADATA_TRANSFORMING` | Profile is in TRANSFORMING status, cannot update metadata |
| `MUST_FILTER_ON_OBJECT_TYPE` | `metadata.list` requires `objectTypeEqual` |
| `MUST_FILTER_ON_OBJECT_ID` | `metadata.list` for ENTRY type requires `objectIdEqual` or `objectIdIn` |
| `METADATA_FILE_NOT_FOUND` | Uploaded metadata file not found |
| `METADATA_PROFILE_FILE_NOT_FOUND` | Profile XSD file not found |
| `METADATA_PROFILE_REFERENCE_EXISTS` | Cannot delete DYNAMIC_OBJECT profile with active references |

**Retry strategy:** For transient errors (HTTP 5xx, timeouts), retry with exponential backoff: 1s, 2s, 4s, with jitter, up to 3 retries. For client errors (`METADATA_ALREADY_EXISTS`, `INVALID_METADATA_DATA`, `INVALID_METADATA_VERSION`), fix the request before retrying. For `INVALID_METADATA_VERSION`, re-read the latest metadata, merge changes, and retry with the current version.




### Best Practices


- **Use systemName for stable profile references.** Set `systemName` on metadata profiles for machine lookups. Display names may change; system names provide a reliable key for code.
- **Include all 4 base type definitions in every XSD.** The KMC relies on `textType`, `dateType`, `objectType`, and `listType` definitions to determine field types for form rendering.
- **Use `<appinfo>` annotations.** Add `label`, `key`, `searchable`, and `description` annotations to every field. This controls KMC rendering and eSearch indexing.
- **One profile per use case.** Create separate profiles for different purposes (e.g., "Content Classification", "Workflow Status", "SEO Tags") rather than one large profile.
- **Use listType with enumerations for filterable fields.** Enum fields are the only type available as KMC filter columns. They also enable dropdown UI controls.
- **Use eSearch for metadata queries.** Use `KalturaESearchEntryMetadataItem` in eSearch for efficient cross-field searching — eSearch is faster and more flexible than `metadata.list` for finding entries by metadata values. See [eSearch API](/docs/rich-media-cms-apis/content-management/esearch-overview).
- **Use optimistic locking for concurrent editing.** Pass the `version` parameter on `metadata.update` to prevent overwrites from concurrent processes.
- **Date fields store Unix timestamps as longs.** Use Kaltura-native `dateType` (based on `xsd:long`) for dates. The KMC DatePicker interprets these as Unix timestamps, not ISO date strings.
- **metadata.list for ENTRY type requires objectId.** Always include `objectIdEqual` or `objectIdIn` when listing entry metadata.
- **Bulk XML updates must include ALL fields.** The system replaces the entire XML document on bulk update. Always include the complete XML with all field values to preserve existing data.
- **Use createMode filter to scope profile listings.** KMC-created profiles use `createMode=2`. API-created profiles use `createMode=1`. Filter with `createModeEqual` to list only profiles relevant to your integration.
- **XML field order must match the XSD sequence.** When adding or updating metadata XML, arrange fields in the exact `<xsd:sequence>` order defined in the schema. The server validates field ordering against the sequence definition. Field names are case-sensitive.
- **4 searchable Date and 4 Integer fields per profile.** Elasticsearch indexes up to 4 Date and 4 Integer fields per metadata profile. Fields beyond this limit are stored and retrievable via `metadata.get`; only the first 4 of each type appear in eSearch. Use text fields for dates/numbers that only need storage and retrieval.
- **`viewsData` controls KMC editor rendering.** The `viewsData` parameter on a metadata profile defines how fields render in the KMC metadata editor (field order, grouping, visibility). When omitted, a default UI is auto-generated from the XSD.