Data Integrity
Validation rules, issues, warnings, and resolution strategies
Data Integrity
Overview
VRPlatform validates data continuously to maintain accounting integrity. When issues are detected, they appear in the issues array on API responses.
Understanding issues helps you:
- Build robust integrations
- Handle edge cases gracefully
- Provide meaningful feedback to users
- Identify and resolve data problems
The Issues Array
Many entities include an issues array:
{
"id": "entity-123",
"status": "active",
"issues": [
{
"code": "locked",
"severity": "warning",
"message": "Cannot modify - data is attached to owner statement",
"context": {
"statementIds": ["stmt-456"]
}
}
]
}Issue Structure
| Field | Description |
|---|---|
code | Machine-readable identifier for programmatic handling |
severity | error (blocking) or warning (informational) |
message | Human-readable description |
context | Additional details specific to the issue type |
Severity Levels
| Severity | Meaning | Action Required |
|---|---|---|
error | Operation blocked or data invalid | Must resolve before proceeding |
warning | Potential problem detected | Review recommended, operation proceeds |
Issue Categories
Locking Issues
Issues related to data locking:
| Code | Severity | Description | Resolution |
|---|---|---|---|
locked | warning | Data cannot be modified | Delete statement or wait for period to reopen |
priorToClosedPeriod | error | Date is before books closed | Use a date after books closed |
Context includes:
reasons- Array of lock reasonsstatementIds- Statements causing the lock
Reservation Issues
Issues with reservations:
| Code | Severity | Description | Resolution |
|---|---|---|---|
guestTotalsMismatch | warning | Calculated totals differ from source | Review payment lines, may need adjustment |
inactiveListing | warning | Reservation on inactive property | Activate listing or mark reservation inactive |
lineNotFound | error | Referenced payment line missing | Check source data, resync if needed |
unassignedAccount | error | Payment line has no account mapping | Configure account mapping for line type |
Owner Statement Issues
Issues with owner statements:
| Code | Severity | Description | Resolution |
|---|---|---|---|
emptyJournalEntryAccountIds | error | Entries missing account assignments | Configure account mappings |
netRevenueLayoutMismatch | error | Layout calculation doesn't match | Review layout configuration |
listingInactive | error | Statement for inactive listing | Activate listing first |
balanceMismatch_start | warning | Starting balance differs from previous end | Check for missed transactions |
balanceMismatch_end | warning | Ending balance calculation differs | Review financials |
unpaidReservations | warning | Reservations with outstanding balances | Consider collecting before publishing |
previousMonthJournalEntries | warning | Entries from prior periods included | May need adjustments |
Context includes:
journalEntryIds- Affected entry IDsaffected- Count of affected items
Statement Row Issues
Issues on individual statement rows:
| Code | Severity | Description |
|---|---|---|
previousPeriodJournalEntries | warning | Row contains entries from prior period |
unpaidReservation | warning | Reservation hasn't been paid |
Account Issues
Issues with accounts:
| Code | Severity | Description | Resolution |
|---|---|---|---|
unassignedAccount | error | Required account not configured | Assign account in settings |
inactiveAccount | warning | Referenced account is inactive | Activate account or use different one |
Ownership Period Issues
Issues with ownership periods:
| Code | Severity | Description | Resolution |
|---|---|---|---|
locked | warning | Period has locked data | Cannot modify dates affecting locked entries |
Statement Layout Issues
Issues with statement layouts:
| Code | Severity | Description | Resolution |
|---|---|---|---|
locked | warning | Layout has attached statements | Cannot modify, create new layout instead |
Context includes:
attachedStatementCount- Number of statements using this layout
Connection Issues
Issues with connections:
| Code | Severity | Description | Resolution |
|---|---|---|---|
credentialsExpired | error | Authentication needs refresh | Re-authenticate the connection |
apiLimitReached | warning | Rate limits exceeded | Wait and retry |
syncFailed | error | Sync operation failed | Check connection settings, retry |
Handling Issues in Integrations
Check Issues on Every Response
const response = await api.getReservation(id);
// Check for errors
const errors = response.issues.filter(i => i.severity === 'error');
if (errors.length > 0) {
// Handle blocking issues
throw new Error(`Reservation has errors: ${errors.map(e => e.code).join(', ')}`);
}
// Log warnings
const warnings = response.issues.filter(i => i.severity === 'warning');
if (warnings.length > 0) {
console.warn('Reservation warnings:', warnings);
}Handle Specific Issue Codes
const issues = response.issues;
// Handle locking
const lockIssue = issues.find(i => i.code === 'locked');
if (lockIssue) {
const { statementIds } = lockIssue.context;
// Inform user which statements are blocking
showMessage(`Data is locked by statements: ${statementIds.join(', ')}`);
}
// Handle missing accounts
const accountIssue = issues.find(i => i.code === 'unassignedAccount');
if (accountIssue) {
const { accountIds } = accountIssue.context;
// Prompt user to configure accounts
redirectToAccountSettings(accountIds);
}Retry Strategies
For transient issues:
async function retryOnRateLimit(operation, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await operation();
} catch (error) {
if (error.code === 'apiLimitReached') {
await sleep(Math.pow(2, i) * 1000); // Exponential backoff
continue;
}
throw error;
}
}
}Best Practices
-
Always check the issues array - Don't assume success just because the request returned 200
-
Distinguish errors from warnings - Errors block operations; warnings are informational
-
Use context for details - The
contextobject provides actionable information -
Log warnings - Even non-blocking issues may indicate data quality problems
-
Surface issues to users - Show meaningful messages, not just error codes
-
Handle common codes explicitly - Build specific handling for codes you expect to encounter
-
Retry transient issues - Rate limits and sync failures may resolve on retry
Related Topics
- Locking - Understanding lock constraints
- Status & Lifecycle - Entity state management
- Accounts - Account validation
- Reservations - Reservation validation
- Owner Statements - Statement validation
