Error Codes

All CRM Service errors follow the standard EventZR envelope format with a machine-readable error code.

Error Envelope

Every error response includes: error.code (machine-readable), error.message (human-readable), error.http (status code), and meta.request_id (for tracing).

Error Response Format

{
  "data": null,
  "error": {
    "code": "ERR_CRM_NOT_FOUND",
    "message": "Contact with id 'abc-123' not found",
    "http": 404
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Error Code Reference (14 codes)

Code	HTTP	Description
ERR_CRM_NOT_FOUND	404	Resource not found (contact, deal, account, etc.)
ERR_CRM_VALIDATION_FAILED	400	Request body validation failed
ERR_CRM_UNAUTHORIZED	401	Missing or invalid JWT token
ERR_CRM_FORBIDDEN	403	Insufficient role permissions
ERR_CRM_CONFLICT	409	Duplicate resource or merge conflict
ERR_CRM_BOOTSTRAP_FAILED	503	Lambda cold start failed — retry request
ERR_CRM_BAD_REQUEST	400	Malformed request (missing fields, wrong types)
ERR_CRM_INTERNAL_SERVER_ERROR	500	Unexpected server error
ERR_CRM_DEAL_ALREADY_CLOSED	409	Deal is already won/lost, cannot modify
ERR_CRM_PIPELINE_HAS_DEALS	409	Pipeline has active deals, cannot delete
ERR_CRM_CONTACT_MERGE_SELF	400	Cannot merge a contact with itself
ERR_CRM_IMPORT_IN_PROGRESS	409	An import is already running for this tenant
ERR_CRM_CONNECTOR_SYNC_FAILED	502	External CRM sync failed (Salesforce, HubSpot, Zoho)
ERR_CRM_RATE_LIMITED	429	Too many requests — retry after backoff