Error Handling & Best Practices - Content Management

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.
• 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.