Common errors

This page collects the errors that recur across multiple API endpoints, regardless of the resource the request refers to. They come from the authentication, permission, identifier-existence, and format checks that apply transversally throughout the API.

401 Unauthorized

The request is not executed because the integration user does not have access to the business or to the part of the organizational structure the requested resource belongs to.

Business forbidden

The business identifier (businessId) sent in the request does not match any business configured in Orquest.

The response includes this text in the message field.

How to fix it

businessId is an account-level identifier configured at the administration level, so there is no API endpoint that lets you look it up.
It is recommended to verify the identifier with the Orquest team or directly in the application.

Forbidden

The business exists, but the integration user has no permissions configured on it.

The response includes this text in the message field.

How to fix it

It is recommended to review the access profile of the integration user within the application and check that the business is assigned to it.
If the user needs access to all of the business’s information, it is recommended to place it at the root node of the hierarchical structure, as detailed in Getting started.

Service or node forbidden

The requested resource (product, service, employee, etc.) exists, but it belongs to a node or service that the integration user has no permissions configured on.

The response includes this text in the message field.

How to fix it

It is recommended to check the business’s organizational structure via Get business nodes or Get business services, to identify which node the resource belongs to.
Once identified, it is recommended to review the user’s visibility over that node within the application.

404 Not Found

An identifier included in the request does not match any record within the specified business. The message identifies the type of resource that was not found, and travels in the message field, inside the errors array.

The exact wording of the message is not uniform across endpoints: the same not-found resource can be described with several different wordings. It is recommended to identify the error by the type of resource it refers to, not by an exact text match.

Employee not found

The employee identifier (employeeId or personId) does not match any employee in the business.

Message variants depending on the endpoint: Employee not found, Person not found, Person <id> does not exist, or Could not find employee with id <id>.

How to fix it

It is recommended to check the available employees via Get employees of a service or Get employees of a product. If you just want to check that a specific identifier exists, Get employee information only needs the businessId and the employeeId.
It is also recommended to check that the identifier used is the employee’s external identifier and not its internal Orquest identifier. The difference between the two is detailed in Identifiers.

Product not found

The product identifier (productId) does not match any product in the business.

Message variants depending on the endpoint: Product not found, Product <id> does not exist, or not exits.

How to fix it

It is recommended to check the products via Get business services, which returns the products linked to each service and only needs the businessId, or Get the products of a service, which is the direct route once the serviceId is already known.

Service not found

The service identifier (serviceId) does not match any service in the business.

The message is not exits.

How to fix it

It is recommended to check the available services via Get business services.

Task not found

The task identifier (locationId) does not match any task configured in the indicated product or service.

The message is Location not found, which in some endpoints arrives with a trailing period (Location not found.).

How to fix it

It is recommended to check the configured tasks via Get tasks by service or Get tasks by product.
It is recommended to check that the identifier matches the one configured in Orquest under Organizational chart > Tasks > External ID.

Node not found

The node identifier (nodeId) does not match any node in the business.

Message variants depending on the endpoint: Node not found, node not found, or Node <id> does not exist.

How to fix it

It is recommended to check the organizational structure via Get business nodes.

User not found

The username (userName) does not match any user in the business.

The message is User not found.

How to fix it

It is recommended to check the existing users via Get all business users or Get user information.

406 Not Acceptable

The request is well-formed, but one of its values cannot be interpreted.

date_parser_error

One of the date parameters in the request (typically from and to) does not have a valid format.

Unlike the other errors on this page, this text appears in the cause field; the message field contains the technical detail of the failed conversion.

How to fix it

It is recommended to always use the yyyy-MM-dd format in date parameters, as indicated in each endpoint’s description.

Summary

These are all the response codes returned by the API and the general reason they appear.

Error code What it’s due to

Error code	What it’s due to
`400 Bad Request`	One of the request’s fields fails business validation: empty required fields, values outside the allowed range, date ranges that are too wide, or inconsistent data. The message identifies the check that failed, and each endpoint documents its own in its "Error codes" section.
`401 Unauthorized`	The integration user does not have access to the business or to the part of the organizational structure the requested resource belongs to. For more information, see 401 Unauthorized.
`404 Not Found`	An identifier included in the request does not match any record within the specified business. For more information, see 404 Not Found.
`406 Not Acceptable`	One of the request’s values cannot be interpreted or does not meet the expected format: malformed dates, fields that don’t match a pattern, values not allowed in a field, or request size limits. For the transversal date case, see 406 Not Acceptable; the rest is documented in each endpoint’s "Error codes" section.
`409 Conflict`	The request conflicts with the current state of the data: an identifier that already exists, records duplicated within the request itself, values that don’t match the business’s configured catalog, or operations that would overwrite information associated with another resource. Each endpoint documents its cases in its "Error codes" section.

400 Bad Request

One of the request’s fields fails business validation: empty required fields, values outside the allowed range, date ranges that are too wide, or inconsistent data. The message identifies the check that failed, and each endpoint documents its own in its "Error codes" section.

401 Unauthorized

The integration user does not have access to the business or to the part of the organizational structure the requested resource belongs to. For more information, see 401 Unauthorized.

404 Not Found

An identifier included in the request does not match any record within the specified business. For more information, see 404 Not Found.

406 Not Acceptable

One of the request’s values cannot be interpreted or does not meet the expected format: malformed dates, fields that don’t match a pattern, values not allowed in a field, or request size limits. For the transversal date case, see 406 Not Acceptable; the rest is documented in each endpoint’s "Error codes" section.

409 Conflict

The request conflicts with the current state of the data: an identifier that already exists, records duplicated within the request itself, values that don’t match the business’s configured catalog, or operations that would overwrite information associated with another resource. Each endpoint documents its cases in its "Error codes" section.