This page provides a reference for the HTTP error codes and associated messages you may encounter while using the DealHub APIs. The errors are organized into common errors that apply across multiple APIs and errors that are specific to a single API.
📘
V1 Endpoints
This page provides error references for the V2 endpoints, such as GET /api/v2/quote/{id} and GET /api/v2/quotes. For errors related to V1 endpoints, please see the V1 Error Reference.
🚧
Placeholders in Error Messages
Error messages often contain placeholders (e.g., <PARAM_NAME>, <entity_id>, <MAX_LENGTH>, [SKU]) that are replaced dynamically with specific values in the actual response.
📘
Asynchronous Errors
Failures for asynchronous operations, such as activating a new version or uploading products, are sent via Failure WebHooks.
Common Errors
These errors can be returned by multiple APIs and typically indicate an issue with the request's format, content, or authentication.
Payload and Validation
HTTP code
When it occurs
Error Message
400
The request payload is not in a valid JSON format.
The Authorization token is missing, invalid, or does not match the user.
Unauthenticated
Entity Not Found
HTTP code
When it occurs
Error Message
400
The requested entity ID (e.g., for a quote, user, or opportunity) does not exist in DealHub.
Entity (ID = <entity_id>) not found
API-Specific Errors
The following errors are unique to specific APIs.
Version API
These errors occur when managing Versions, Product Catalogs, and Hierarchies.
Version Management
HTTP Code
When it occurs
Error Message
400
Mismatch between domain name of the source version account and target version account during duplication.
The domain name of the source version account does not match the target version account
400
A request is made to activate a version that is already active.
Version (id= <version_id>) already active.
400
The name provided for a new version is not unique.
A new version name should be unique. [cite_start]Please change the name and try again.
400
An operation was attempted on a version with an invalid status (e.g., modifying an Active version).
Specified version cannot be modified: Invalid version status.
400
A request was made to fetch 'MODIFIED' products for a version in 'DRAFT' status.
'MODIFIED' products option is not available for version in 'DRAFT' status. [cite_start]Fetch 'ALL' products instead.
400
No version ID was provided, and the system could not find an 'ACTIVE' version to use as default.
Could not find the 'ACTIVE' version.
Product Hierarchy & Catalog
HTTP Code
When it occurs
Error Message
400
Specific SKUs requested by the consumer were not found in the version.
The following SKUs not found: <LIST_OF_SKUS>
400
The number of SKUs in a fetch request exceeds the allowed limit.
The number of requested items exceeds the allowed limit of <MAX_LIMIT>.
400
The SKU provided in a hierarchy update does not exist in the product list.
The SKU [SKU] at [path] does not exist in the products list. [cite_start]Please add the SKU...
400
A SKU or Label name field is empty.
Invalid data found at [path], SKU/ Label name field cannot be empty.
400
The type field is invalid or empty (must be PRODUCT, LABEL, or BUNDLE).
The field type is invalid / The field type is not defined.
400
A label name exceeds the character limit (50 chars).
A label name cannot exceed 50 characters.
400
A SKU exceeds the character limit (200 chars).
A SKU cannot exceed 200 characters.
400
A label name contains invalid characters.
The label name contains invalid characters.
400
Structure: A label exists without any children (products/bundles).
Label [name] is set without any related products.
400
Structure: A label is mandatory but has no mandatory child products.
Label [name] is a mandatory label without any mandatory products.
400
Structure: An alternative item does not have at least one peer option at the same level.
[Item NAME] has incomplete configuration. [cite_start]Please ensure there is at least one more alternative at the same level...
400
Structure: Mismatch in mandatory/alternative settings among peer items.
For [name], you have an alternative option in this level, and one is set as mandatory. [cite_start]Please set all fields as both mandatory and alternative.
400
Validation:mandatory or alternative fields are empty or invalid.
The item "[name]" has an empty/invalid mandatory or alternative field.
400
The hierarchy exceeds the maximum depth of 10 levels.
You have reached the maximum limit of 10 levels that can be added.
400
The hierarchy exceeds the maximum item limit (50,000).
You can only add a maximum of 50,000 products or labels to the product hierarchy.
400
Delete: Attempt to delete a product that has children.
Unable to delete product [SKU] that has related product/s in the product hierarchy.
400
Delete: Attempt to delete a product marked as Mandatory or Alternative.
Unable to delete product [SKU] that was set as [mandatory/alternative] in the product hierarchy.
Actions API
The following errors are specific to the Actions API and may occur when performing submit, publish, or sign externally actions on quotes.
HTTP Code
When it occurs
Error Message
400
The quote cannot be submitted due to failing submit validation.
Submission failed: The quote did not pass submit validation requirements.
400
The quote cannot be published due to failing submit validation.
Publish quote failed: The quote did not meet submit validation requirements.
400
The quote was created but cannot be signed due to failing submit validation.
Sign externally failed: The quote did not pass submit validation requirements.
400
The quote cannot be published due to a required approval.
Publish quote failed: Approval is required before the quote can be published.
400
The quote cannot be signed due to a required approval.
Sign externally pending: Approval is required before the quote can be signed.
400
The quote cannot be submitted because it has already been submitted.
Submission failed: The quote has already been submitted.
400
The quote cannot be published; the quote document type is not DealRoom.
Publish quote failed: The quote's document type must be 'DealRoom' to proceed.
400
The quote cannot be published because it has already been published.
Publish quote failed: The quote has already been published.
400
The quote cannot be published because its status is 'Draft'; it must be submitted first.
Publish quote failed: The quote is in 'Draft' status and must be submitted first.
400
The quote cannot be signed because it has already been signed.
Sign externally failed: The quote has already been signed.
400
The quote cannot be signed externally.
Sign externally failed: The request cannot be processed.
400
Failed to sign externally; the quote is partially signed.
Sign externally failed: The quote is currently in the signing process and cannot be signed externally at this stage.
400
Failed to sign externally; DealRoom has an active redline.
Sign externally failed: The DealRoom is in the redlining process. External signing is only allowed after redlining is completed.
400
Failed to submit; the draft quote requires an update before submission.
Submission failed: The draft quote requires updates before it can be submitted. Complete updates via the DealHub UI.
400
Failed to sign externally; Because a published quote has already existed in the opportunity.
Sign externally failed: There is already another published quote's document type 'DealRoom' in the opportunity. Published the quote to sign it externally.
400
Failed to sign the quote externally; The quote failed to sync.
Sign quote externally failed: The quote failed to sync.
400
Failed to sign the quote externally; The quote status is draft.
Sign quote externally failed: The quote is in a draft status.
400
Failed to sign the quote externally; The option to multi-sign externally is on and the quote needs to be published to sign it externally.
Sign quote externally failed: There is already a signed quote under the opportunity. The quote needs to be published first.
Quote API
HTTP Code
When it occurs
Error Message
400
A document is requested for a quote that is still in Draft status.
Cannot retrieve the document for the quote in 'Draft' status.
400
A document is requested, but the quote was generated as an Excel file and has no document template specified.
The quote does not have a template specified.
400
The requested document type (e.g., PDF, WORD) is not enabled for the quote's playbook.
<DOCUMENT_TYPE> is not supported by the quote playbook.
400
The requested file type for a submitted quote is different from the type it was originally generated with.
Cannot generate <DOCUMENT_TYPE> for the submitted quote (submitted with <FILE_TYPE>)
400
An API request is made when no version is currently active in the account.
Cannot complete request execution as there is no active Version configured.
400
Signer information is requested for an opportunity that does not have a published DealRoom.
No DealRoom instance found for the given opportunity ID
400
A request is made to create a new opportunity, but an opportunity with the same ID already exists.
