Sync & Integration Errors

This guide helps administrators and integration developers diagnose failures when EGKits exchanges data with external systems via REST API, webhooks, scheduled imports, or middleware connectors. Symptoms include partial imports, duplicate records, HTTP 4xx/5xx responses, and webhook retry exhaustion.

#Integration architecture overview

External System  <--REST API-->  EGKits Tenant
       ^                              |
       |         Webhooks             |
       +------------------------------+

#Before you begin

Ensure clocks are synchronized (NTP) on integration servers — timestamp skew causes signature validation failures.

#Symptom: HTTP 401 Unauthorized

#Diagnostic steps

1. Verify API key is active and not expired.
2. Confirm Authorization header format: Bearer {token} or documented scheme.
3. Check key scopes include the target module (for example invoicing:write).
4. Regenerate key if compromised; update all calling systems.

#Resolution matrix

#Symptom: HTTP 400 Bad Request / validation errors

#Diagnostic steps

1. Parse response body — EGKits returns field-level validation messages.
2. Compare payload against API Reference schema for the endpoint version.
3. Verify required foreign keys exist (customer ID, product SKU, GL account code).
4. Check date formats (ISO 8601) and decimal precision for amounts.
5. Confirm fiscal period is open for financial transactions.

#Resolution matrix

#Symptom: HTTP 429 Rate limit exceeded

#Diagnostic steps

1. Review Retry-After response header.
2. Inspect integration batch size — reduce concurrent requests.
3. Implement exponential backoff in client code.
4. Contact account manager if sustained throughput exceeds tier limits.

#Resolution matrix

#Symptom: Webhook not received or failing

#Diagnostic steps

1. Open Administration > Integrations > Webhooks and review delivery log.
2. Confirm endpoint URL is HTTPS with valid TLS certificate.
3. Verify webhook secret matches HMAC validation on receiver.
4. Check receiver returns HTTP 2xx within timeout (default 30 seconds).
5. Inspect retry count — exhausted retries mark event as dead letter.

#Resolution matrix

#Symptom: CSV import partial failure

#Diagnostic steps

1. Download import result log with row numbers and error messages.
2. Validate CSV encoding (UTF-8 with BOM for Arabic text).
3. Confirm column headers match template exactly.
4. Check for duplicate natural keys (SKU, customer code, account code).
5. Re-import failed rows only after correction.

#Resolution matrix

#Symptom: Duplicate or missing records after sync

#Diagnostic steps

1. Verify idempotency keys on create operations (API clients).
2. Check for retry logic that replays POST without idempotency.
3. Review external ID mapping table in middleware.
4. Compare record counts between systems using reconciliation reports.
5. Inspect Audit Trail for duplicate create events with same correlation ID.

#Resolution matrix

#Monitoring and prevention

#Escalation checklist

1. Tenant URL and integration name.
2. HTTP status code and full response body (redact secrets).
3. Sample request payload (anonymized).
4. Webhook delivery ID or import batch ID.
5. Timestamp range of failures.

#Related links

• API Reference — endpoints, auth, and pagination
• Migration Guide — version upgrades and breaking changes
• Data Entry Standards — import field conventions
• System Configuration Guide — integration settings
• Audit Trail Guide — API activity investigation