Handle Intent API Errors

The Demandbase Intent API returns an HTTP status code and a JSON response body when a request fails. Use the error code and diagnostic information to identify and resolve the issue.

Understand Intent API Error Responses

An error response includes the following fields:

Field	Description
`errorCode`	Identifies the specific error. Use this value to handle errors programmatically.
`errorMessage`	Describes the error and helps you identify how to correct it.
`diagnosticCode`	Identifies the request for troubleshooting with Demandbase Support.

Example error response:

{
  "errorCode": "400-218",
  "errorMessage": "At least one of companyIds, keywordSetIds, or keywords must be provided for intent search.",
  "diagnosticCode": "ccb84f25-236e-4bcf-be01-88b7dd673fb4"
}

Important:

Use errorCode instead of errorMessage when handling errors programmatically. Error messages may change.
The API reports only the first validation error. Correct the error and resend the request to identify any additional errors.

Understand Intent API HTTP Status Codes

The following HTTP status codes indicate why an Intent API request failed.

HTTP Status	Description
`400 Bad Request`	The request contains invalid parameters, exceeds a limit, or uses unsupported values.
`401 Unauthorized`	The bearer token is missing, invalid, expired, or unsupported.
`403 Forbidden`	The API key set does not include Intent API access.
`404 Not Found`	The keyword set does not exist in your tenant.
`409 Conflict`	Another keyword set already uses the specified name.
`429 Too Many Requests`	A rate limit or account quota has been reached.
`500 Internal Server Error`	An unexpected server error occurred.
`502 Bad Gateway`	An upstream service returned an error.
`503 Service Unavailable`	The service is temporarily unavailable.
`504 Gateway Timeout`	The request timed out.

Understand Company Intent Validation Errors

The following error codes identify invalid requests to the Company Intent endpoint.

Error code	Description
`400-103`	A company ID is not numeric.
`400-109`	`sortOrder` contains an unsupported value.
`400-166`	The request body is missing or contains invalid JSON.
`400-218`	The request does not include `companyIds`, `keywordSetIds`, or `keywords`.
`400-219`	The request includes more than 10 company IDs.
`400-220`, `400-221`	A required date is missing or does not use the `yyyy-MM-dd` format.
`400-222`	`startDate` is later than `endDate`.
`400-223`	The date range exceeds 12 months.
`400-224`	`intentStrength` contains an unsupported value.
`400-225`	The people-researching range contains a negative value, or the minimum exceeds the maximum.
`400-226`	`pageSize` is outside the supported range of 1–100.
`400-227`	`sortBy` contains an unsupported value.
`400-229`	The request includes more than 10 keyword set IDs.
`400-230`	The request includes more than 50 keywords.
`400-232`	The request includes `pageToken`, which is not supported during the beta.

Important: Company Intent pagination is not supported during the beta. To retrieve different results beyond the first page, narrow your filters or shorten the date range.

Understand Keyword Sets Validation Errors

The following error codes identify invalid requests to the Keyword Sets endpoints.

Error code	Description
`400-166`	The create request body is missing or contains invalid JSON.
`400-233`	The required name field is missing when creating a keyword set.
`400-234`	A keyword is blank, null, or exceeds 255 characters.
`400-235`	A seed URL is invalid.
`400-236`	The keyword set ID is not a positive integer.
`400-237`	sortBy contains an unsupported value.
`400-238`	sortOrder contains an unsupported value.
`400-239`	page or perPage is not numeric or is outside the supported range.
`400-240`	Your tenant has reached the maximum number of keyword sets.
`400-241`	A keywords or seedUrls object in an update does not specify any changes.
`400-242`	The update request does not include a recognized property.
`400-243`	The same value appears in both add and remove.
`400-244`	The keyword set name is blank or exceeds 255 characters.
`400-245`	The request exceeds the maximum number of seed URLs per keyword set.
`400-246`	The required keywords field is missing when creating a keyword set. An empty array is allowed.
`400-247`	isCompetitor is not a boolean when creating a keyword set.
`400-248`	The request exceeds the maximum number of keywords per keyword set.
`400-249`	The keyword set does not have enough capacity for the up to 100 keywords a new seed URL can generate.
`404-106`	The keyword set does not exist in your tenant.
`409-101`	Another keyword set already uses the specified name. Keyword set names are case-sensitive.

Troubleshoot Intent API Errors

Use the following troubleshooting steps to resolve common Intent API errors.

Error	Recommended Action
`400 Bad Request`	Review errorMessage, correct the invalid parameters or values, and resend the request.
`401 Unauthorized`	Refresh or replace the bearer token.
`403 Forbidden`	Ask your Demandbase administrator to verify that your API key set includes Intent API access.
`400-240`	Delete an unused keyword set in the Demandbase One UI or contact Demandbase Support to request a higher limit.
`429 Too Many Requests`	Reduce concurrent requests and retry after a delay.
`500`, `502`, `503`, `504`	Retry transient errors using exponential backoff with jitter.

Important: Before retrying a Keyword Sets write request that returns 500 or 504, retrieve the keyword set to verify whether the changes were applied. The original request may have partially succeeded.

If the issue persists, contact Demandbase Support and include the diagnosticCode from the error response to help identify the failed request.