Skip to main content
All errors use a consistent envelope. The exact shape differs slightly between validation errors and business logic errors. Validation errors (400 from DTO checks, fired before any database call): 
{
  "statusCode": 400,
  "timestamp": "2026-04-28T10:15:00.000Z",
  "path": "/api/v1/accounts",
  "message": "Bad Request",
  "data": [
    {
      "property": "domain",
      "constraints": { "isNotEmpty": "domain should not be empty" }
    }
  ]
}
data contains the raw class-validator error objects. There is no customMessage on validation errors. Business logic errors (thrown by the service or controller): 
{
  "statusCode": 400,
  "timestamp": "2026-04-28T10:15:00.000Z",
  "path": "/api/v1/accounts",
  "message": "Bad Request",
  "customMessage": "Segment 'abc' is not active or draft and cannot accept new members",
  "data": null
}
customMessage is present only when the service explicitly sets it. Use it for logging and user-facing messages.

​
401 Unauthorized

Applies to every endpoint.
ConditioncustomMessage
X-Api-Key header missingX-Api-Key header is required
Key not found or invalidInvalid API key

​
400 Bad Request — validation

Fires before any database call. data contains the raw class-validator error objects.
EndpointField / ruleExample customMessage
POST /accountsaccounts — empty or missingaccounts must be an array
POST /accountsaccounts — more than 100 itemsaccounts must contain no more than 100 elements
POST /accountsdomain — missingdomain should not be empty
POST /accountsname — missingname should not be empty
POST /dealsdeals — more than 100 itemsdeals must contain no more than 100 elements
POST /dealsexternalDealId — missingexternalDealId should not be empty
POST /dealsstartDate / closedDate — not ISO 8601startDate must be a valid ISO 8601 date string
POST /dealsownerEmail — not a valid emailownerEmail must be an email
POST /sales-activitiesactivities — more than 50 itemsactivities must contain no more than 50 elements
POST /sales-activitiesoccurredAt — missing or not ISO 8601occurredAt must be a valid ISO 8601 date string
POST /sales-activitiesdomain — missingdomain should not be empty
POST /sales-activitiesownerEmail — missing or invalidownerEmail must be an email
POST /sales-activitiescontacts — missing or emptycontacts must contain at least 1 elements
POST /sales-activitiesdirection — not inbound or outbounddirection must be one of the following values: inbound, outbound
POST /accounts/custom-fieldlabel — missinglabel should not be empty
POST /accounts/custom-fieldlabelType — invalid valuelabelType must be one of the following values: singleLineText, ...
POST /accounts/custom-fieldoptions — missing when requiredoptions must contain at least 1 elements
GET /accountslastSync — invalid formatlastSync must be a valid ISO 8601 date string
PATCH /accounts/external-idsmappings — more than 100 itemsmappings must contain no more than 100 elements

​
400 Bad Request — business logic

EndpointConditioncustomMessage
POST /accountssegmentId not foundSegment '<id>' not found
POST /accountssegmentId is a dynamic segmentSegment '<id>' is not a static segment
POST /accountssegmentId status is not active or draftSegment '<id>' is not active and cannot accept new members
PUT /accounts/:rtp_aidrtp_aid is not a valid formatInvalid rtp_aid format
PUT /accounts/:rtp_aidcustomFields keys not definedCustom field key(s) not found: KEY_C. Unable to update this account.

​
404 Not Found

EndpointConditioncustomMessage
PUT /accounts/:rtp_aidNo account matches rtp_aidAccount with rtp_aid '<id>' not found

​
500 Internal Server Error

message is always Internal server error. Do not parse customMessage — use it for logging only. Safe to retry with exponential back-off.

​
Per-item errors in batch endpoints

POST /accounts, POST /deals, and POST /sales-activities always return HTTP 200. Check each item’s status field in results.
EndpointItem statusCause
POST /accountsfailedDomain already exists — use PUT /accounts/:rtp_aid to update
POST /accountsfailedUnknown custom field key in customFields
POST /dealsfailedPipeline already exists e.g. Pipeline(s) already exist: smb-pipeline
POST /sales-activitiesfailedDuplicate externalActivityId
POST /sales-activitiesskippedactivityType is not call or email