Integration Issues

This guide resolves failures during integration authentication, sync, and ongoing health checks.

Failure Categories

• OAuth connect/authentication failures
• Token expiry and re-authorization drift
• Field mapping errors during CRM sync
• Permission mismatches in downstream systems

Diagnosis Workflow

1. Check integration status and last sync event.
2. Identify error signature from latest failed action.
3. Validate account scopes and downstream permission model.
4. Reconnect integration and run one controlled test action.
5. Confirm success and monitor next scheduled sync.

Error Signatures

• oauth_denied: account consent not granted for required scopes.
• token_expired: refresh failed; reconnect required.
• mapping_invalid: field type or required-field mismatch.
• downstream_permission_denied: integration user lacks destination write rights.

Preventive Controls

• Use dedicated integration service accounts.
• Review OAuth scopes quarterly.
• Validate mappings in sandbox before production changes.
• Assign one owner per integration to avoid unowned failures.

Escalate persistent failures with error code, provider account id, and test action timestamp.