Tenant API

Errors

Every error response documented across the Tenant API, grouped by status code. 139 documented failure modes in total.

Error envelope

Failures return a JSON body with the HTTP status repeated in statusCode, a short error label, and a message describing what went wrong. Validation failures may return several messages at once.

application/json

{
  "statusCode": 400,
  "message": [
    "pageSize must not be greater than 50"
  ],
  "error": "Bad Request"
}

Status codes

40094 documented

The request was rejected before it reached your data — a missing field, a value out of range, or a reference that could not be resolved.

40114 documented

Authentication failed. The bearer token is missing, malformed or expired.

4036 documented

Authenticated, but not permitted. Usually the request origin is not on the allowlist for your integration.

40415 documented

A referenced entity does not exist, or is not visible to your tenant.

4062 documented

The request could not be satisfied in the format requested.

4091 documented

The request conflicts with the current state of the resource.

5004 documented

An unexpected server error. Safe to retry with backoff; contact support if it persists.

5022 documented

See the table below.

5031 documented

The service is temporarily unavailable. Retry with backoff.

400 Bad Request

The request was rejected before it reached your data — a missing field, a value out of range, or a reference that could not be resolved.

Code	When it happens	Endpoints
—	dateAssignment is missing or malformed (type not one of the accepted values, timeRange without type or numeric value).	Reschedule Booking
—	A referenced entity could not be resolved: service variant, product (by sku), product unit (by serial), or providerReference not found. Also when productUnits length exceeds quantity.	Create work order
—	id is not a positive integer, or serialNumber is empty.	Get Full Product Unit
—	Missing or invalid fields, an invalid/unknown dynamic form, or an item that cannot be resolved (e.g. product, product unit, or warranty not found).	Create acquisition
—	Invalid extendedWarrantyStartMode, or extendedWarrantyStartDate missing or invalid when extendedWarrantyStartMode is "CUSTOM_DATE".	Create acquisition
—	A pagination parameter has the wrong type or is out of range (for example pageSize above 50).	Get Product Units by Customer Get Bookings by Customer
—	The referenced product is not a component, the component lookup type is not supported, an area id is not numeric, an area reference is ambiguous, an area appears in more than one group, or a group mixes areas of different currencies.	Update Component Price/Cost
`_(validation messages)_`	One or more fields are missing or invalid. The body carries message as an array of strings, one per failed validation.	Add New Product Unit Start Maintenance Plan
`\NO\_ACTIVE\_ADDON\_OPERATION\_FOUND\_FOR: ADDON\_{ID`	SKU}: {value} VARIANT\_ID: {variantId}\	Check Options
`ADDON_ID_IS_NOT_A_VALID_POSITIVE_INTEGER`	An "addonId" value is not a positive integer.	Check Options Obtain Dates Obtain Times
`Address {id} has no customer associated`	The address is a customer address but has no customer linked to it.	Add New Product Unit
`Address {id} is not a customer address`	The address exists but is not associated to a customer entity.	Add New Product Unit
`Address {id} not found`	No Sodtrack address exists with that ID.	Add New Product Unit
`ADDRESS_REFERENCE_NOT_SUPPORTED`	address.type was sent as addressReference. Resolution by external address reference is not yet supported; use addressId.	Add New Product Unit
`BOOKING_CANNOT_BE_RESCHEDULED: status {status}`	The booking is in execution, done or cancelled.	Reschedule Booking
`BOOKING_NOT_FOUND_FOR_ID`	No booking found for the given entity ID.	Create Incident
`BOOKING_NOT_FOUND_FOR_REFERENCE`	No booking found for the given entity reference.	Create Incident
`Date is required when type is DIRECT`	dateAssignment.date is missing.	Reschedule Booking
`ENTITY_IDENTIFIER_REQUIRED`	entity.value is missing or empty.	Create Incident
`ENTITY_TYPE_NOT_SUPPORTED`	entityType is not supported for creation. Only booking, lead, and work_order are supported.	Create Incident
`Exactly one of id or sku must be provided`	Neither or both identifiers were sent.	Product
`FIELD_REFERENCE_IS_REQUIRED`	A qualifying question entry is missing fieldReference.	Create Lead
`id must be an integer number / id must not be less than 1`	id is not a positive integer.	Get bookings Product
`INCIDENT_NOT_FOUND`	No incident found for the given ID or reference.	Update Incident
`INCIDENT_REASON_NOT_FOUND`	The incident reason ID does not exist in Sodtrack.	Create Incident
`INCIDENT_REASON_REFERENCE_NOT_SUPPORTED`	Resolution by reasonReference is not yet supported. Use reasonId.	Create Incident
`INCIDENT_STATUS_NOT_FOUND`	The incident status ID does not exist in Sodtrack.	Update Incident
`INCIDENT_STATUS_REFERENCE_NOT_SUPPORTED`	Resolution by statusReference is not yet supported. Use statusId.	Update Incident
`Invalid addressId: {value}`	address.value is not a positive integer.	Add New Product Unit
`Invalid productId: {value}`	product.value is not a positive integer when product.type is productId.	Add New Product Unit
`INVALID_ACCOUNTABLE_USER`	accountableUser was provided but could not be resolved to an existing user.	Update Incident
`INVALID_CREATOR_USER`	creatorUser was provided but could not be resolved.	Create Incident
`INVALID_DATE: expected ISO 8601`	dateAssignment.date is not a valid ISO 8601 date.	Reschedule Booking
`INVALID_INCIDENT_REASON_ID`	Reason id must be a number.	Create Incident
`INVALID_INCIDENT_REASON_TYPE`	Invalid incident reason identifier type.	Create Incident
`INVALID_INCIDENT_STATUS_ID`	Status id must be a number.	Update Incident
`INVALID_INCIDENT_STATUS_TYPE`	Invalid incident status identifier type.	Update Incident
`INVALID_INCIDENT_TYPE`	Invalid incident identifier type (must be incidentId or incidentReference).	Update Incident
`INVALID_LATITUDE_OR_LONGITUDE`	address.coordinate was sent with lat/lng outside valid ranges (lat -90–90, lng -180–180).	Create Lead
`INVALID_PHONE_NUMBER`	phoneNumber could not be parsed as a valid phone number.	Search Customers
`INVALID_QUALIFYING_QUESTION_WITH_ID_REFERENCE: {fieldReference}`	A qualifying question fieldReference does not match any dynamic field for the service’s lead form.	Create Lead
`INVALID_REPORTER_USER`	reporterUser was provided but could not be resolved.	Create Incident
`INVALID_SALES_CHANNEL`	The given saleChannel was not found (in strict mode).	Create booking
`INVALID_SALES_CHANNEL`	The given salesChannelId does not exist or is invalid.	Create Lead
`INVALID_SALES_CHANNEL`	saleChannel.value is not a valid sales channel reference, or is not a positive integer when type is "id".	Create work order
`INVALID_SALES_CHANNEL`	The sale channel could not be resolved from saleChannel.	Create acquisition
`INVALID_SERVICE`	The given serviceId does not exist or has no associated lead form.	Create Lead
`INVALID_STATUS_TO_RESOLVE_APPROVAL`	The budget execution is not in a status that accepts an approval decision, typically because it was already approved.	Approve budget execution Reject budget execution
`INVALID_USER_TYPE`	Invalid user identifier type.	Create Incident
`INVALID_WORK_ORDER_ID`	entity.value is not a number when resolving a work order by ID.	Create Incident
`InvalidParameters`	One or more required fields are missing or invalid.	Create booking Project Creation Create Note Create Transaction Create Incident Update Incident
`InvalidParameters`	One or more required fields are missing or invalid (e.g. validation pipeline).	Create Lead
`InvalidParameters`	A required field is missing or invalid (e.g. quantity < 1, or type not in the allowed values for variant / product / product units).	Create work order
`InvalidParameters`	budgetExecutionId is not a number.	Get Budget Execution Detail
`InvalidParameters`	A required field (sku, name) is missing or a field has an invalid value (e.g. unsupported type).	Create product
`InvalidParameters`	The product selector is missing/invalid, or product.type is not "productId" / "productSku".	Update product
`InvalidParameters`	A query parameter is not an integer or falls outside its allowed range: id or bookingId below 1, pageNumber below 1, or pageSize outside 1–50.	Search Customers
`InvalidParameters`	customerId is not a valid integer.	Get Customer
`InvalidParameters`	customerId is not a number, or a pagination parameter is not an integer or falls outside its allowed range.	Get Budget Execution by Customer
`InvalidParameters`	Missing or invalid request parameters.	Available Dates Available Hours by Date
`LEAD_NOT_FOUND`	The lead could not be found for the given leadId or leadReference.	Create Note
`LEAD_NOT_FOUND_FOR_ID`	No lead found for the given entity ID.	Create Incident
`LEAD_NOT_FOUND_FOR_REFERENCE`	No lead found for the given entity reference.	Create Incident
`MAINTENANCE_PLAN_EXECUTION_ALREADY_IN_PROGRESS`	The unit already has an open cycle (PENDING or IN_PROGRESS) for this execution variant.	Start Maintenance Plan
`MAINTENANCE_PLAN_NOT_EXISTS`	No maintenance plan covers the unit's product for the given execution variant.	Start Maintenance Plan
`MAINTENANCE_RULE_NOT_EXISTS`	The plan exists but holds no rule for the given execution variant.	Start Maintenance Plan
`MULTIPLE_BOOKINGS_FOUND_FOR_REFERENCE`	More than one booking shares the given reference.	Create Incident
`MULTIPLE_CUSTOMERS_FOUND_FOR_REFERENCE`	More than one customer matches the provided reference/email; resolution is ambiguous. Use a unique reference or contact.	Project Creation
`MULTIPLE_INCIDENTS_FOUND_FOR_REFERENCE`	More than one incident matches the given reference.	Update Incident
`NO_ACTIVE_ADDON_OPERATION_FOUND_FOR: ADDON_{ID`	SKU}: {value} VARIANT_ID: {variantId}	Obtain Dates Obtain Times
`NO_COVERAGE_FOR_ADDON: {addonId} (Reference: {reference})`	The addon is not offered at the location.	Check Options Obtain Dates Obtain Times
`NO_VARIANT_FOUND_FOR_ID / NO_VARIANT_FOUND_FOR_SKU`	A variant could not be found by its id or SKU.	Check Options Obtain Dates Obtain Times
`One or more required fields are missing or invalid.`	—	Upsert variants and providers
`pageNumber must not be less than 1`	pageNumber out of range.	Get bookings
`pageSize must not be greater than 50 / pageSize must not be less than 1`	pageSize out of range.	Get bookings
`Product not found in the product module: sku={value}`	No catalog product matches the given SKU.	Add New Product Unit
`PRODUCT_NOT_EXISTS`	The unit has no catalog product associated, so no plan can be matched.	Start Maintenance Plan
`PRODUCT_UNIT_NOT_EXISTS`	No product unit matches the given ID or serial number.	Start Maintenance Plan
`PRODUCT_UNIT_SERIAL_NUMBER_AMBIGUOUS`	The serial number matches units of more than one product. Use productUnitId.	Start Maintenance Plan
`PROJECT_REFERENCE_ALREADY_USED: {reference}`	A project with the given reference already exists. The reference must be unique.	Project Creation
`Provide exactly one of \id\ or \serialNumber\\`	Neither identifier was sent, or both were.	Get Full Product Unit
`REQUIRES_ADDRESS_OR_ZIP_CODE`	The service is not an in-store service and the request did not include coordinates, address text, or zip code.	Create Lead
`Service variant not found: type={type}, value={value}`	No service variant matches the given ID or SKU.	Start Maintenance Plan
`TIME_RANGE_NOT_FOUND: {type} {value}`	No time range matches the id or index sent.	Reschedule Booking
`Validation error`	A query parameter has an invalid value: id or customerId is not a positive integer, pageSize is outside 1–50, or pageNumber is below 1. The response body lists the offending parameters.	Projects
`Validation error`	A query parameter has an invalid value: id or bookingId is not a positive integer, pageSize is outside 1–50, or pageNumber is below 1. The response body lists the offending parameters.	Search customers (Deprecated)
`Validation failed (numeric string is expected)`	bookingId is not an integer.	Reschedule Booking
`Validation failed (numeric string is expected)`	customerId is not an integer.	Get Product Units by Customer Get Bookings by Customer
`Validation message, e.g. date must be a valid ISO 8601 date string`	A field is missing, has an invalid value, or a variant or addon is repeated.	Obtain Times
`Validation message, e.g. variants should not be empty, quantityOfDays must not be greater than 31`	A field is missing, has an invalid value, or a variant or addon is repeated.	Check Options
`Validation message, e.g. variants should not be empty, startDate must be a valid ISO 8601 date string`	A field is missing, has an invalid value, or a variant or addon is repeated.	Obtain Dates
`VARIANT_ID_IS_NOT_A_VALID_POSITIVE_INTEGER`	A "variantId" value is not a positive integer.	Check Options Obtain Dates Obtain Times
`WORK_ORDER_NOT_FOUND_FOR_ID`	No work order found for the given entity ID.	Create Incident
`WORK_ORDER_NOT_FOUND_FOR_REFERENCE`	No work order found for the given entity reference.	Create Incident

401 Unauthorized

Authentication failed. The bearer token is missing, malformed or expired.

Code	When it happens	Endpoints
—	API key missing or invalid, or the request does not come from an authorized network.	Get bookings
—	Authentication token missing or expired.	Create booking Project Creation Create Lead Create Note Add New Product Unit Create Transaction Create Incident Update Incident Start Maintenance Plan
—	Missing or invalid x-api-key, or the request does not come from an authorized origin.	Reschedule Booking Get Full Product Unit Get Product Units by Customer Get Bookings by Customer
—	The API key is missing or invalid.	Check Options Obtain Dates Obtain Times
—	x-api-key is missing or invalid, or the request does not originate from an authorized network.	Projects Search customers (Deprecated)
—	Missing or invalid x-api-key.	Create work order Create product Update product
—	x-api-key is missing or invalid.	Get Budget Execution Detail Get Budget Execution by Customer
—	The API key is missing, invalid, or the request origin is not authorized.	Approve budget execution Reject budget execution
—	API key missing or invalid.	Create acquisition
—	x-api-key is missing or invalid, or the request does not reach Sodtrack through the authorized network.	Search Customers Get Customer
—	API key missing/invalid, or request not from an authorized network.	Update Component Price/Cost
—	Missing or expired authentication token.	Available Dates
—	Authentication failed or token expired.	Available Hours by Date
`Authentication token missing or expired.`	—	Upsert variants and providers

403 Forbidden

Authenticated, but not permitted. Usually the request origin is not on the allowlist for your integration.

Code	When it happens	Endpoints
—	The request origin is not allowed.	Get bookings Product
—	The API key or origin is not authorized.	Create booking Project Creation Create Lead Create Note Add New Product Unit Create Transaction Create Incident Update Incident Start Maintenance Plan
—	Origin not authorized for the inbound integration network.	Create acquisition
—	The API key or origin is not authorized to access this resource.	Available Dates
—	The API key or origin is not authorized to access this endpoint.	Available Hours by Date
`The API key or origin is not authorized.`	—	Upsert variants and providers

404 Not Found

A referenced entity does not exist, or is not visible to your tenant.

Code	When it happens	Endpoints
—	A referenced variant, provider, project, or channel could not be found.	Create booking
—	saleChannel.type is "id" and no sales channel exists with that id.	Create work order
—	No product exists for the given id or sku.	Update product
—	The component (by id/SKU) or a referenced area (by id/reference) was not found.	Update Component Price/Cost
—	The specified variant or provider does not exist or is not linked to the given location.	Available Dates
—	No availability found for the given date or parameters.	Available Hours by Date
`A referenced variant, provider, or area could not be found.`	—	Upsert variants and providers
`ADDRESS_NOT_FOUND`	addressId does not match an existing address.	Check Options Obtain Dates Obtain Times
`BOOKING_NOT_FOUND: {bookingId}`	No booking exists with that id.	Reschedule Booking
`BUDGET_EXECUTION_NOT_FOUND`	No budget execution exists for the given id.	Approve budget execution Reject budget execution
`BUDGET_EXECUTION_NOT_FOUND: {budgetExecutionId}`	No budget exists with that id, or the id belongs to a budget template.	Get Budget Execution Detail
`CUSTOMER_NOT_FOUND: {customerId}`	No customer exists with that id, or the id belongs to a Sodtrack user that is not a customer.	Get Customer
`CUSTOMER_NOT_FOUND: {customerId}`	No customer exists with that id.	Get Product Units by Customer Get Bookings by Customer Get Budget Execution by Customer
`Product with id {id} not found / Product with sku '{sku}' not found`	No product matches the identifier.	Product
`PRODUCT_UNIT_NOT_FOUND: {identifier}`	No product unit exists with that id or serial number. The message echoes the identifier sent.	Get Full Product Unit

406 Not Acceptable

The request could not be satisfied in the format requested.

Code	When it happens	Endpoints
`PRODUCT_UNIT.SERIAL_NUMBER_ALREADY_IN_USE`	The generated serial number collided with an existing one. Rare; retry the request.	Add New Product Unit
`PRODUCT.SKU_ALREADY_IN_USE`	A product with the given sku already exists.	Create product

409 Conflict

The request conflicts with the current state of the resource.

Code	When it happens	Endpoints
`ACQUISITION_ALREADY_EXISTS`	An acquisition already exists for the given reference.	Create acquisition

500 Internal Server Error

An unexpected server error. Safe to retry with backoff; contact support if it persists.

Code	When it happens	Endpoints
—	Unexpected server error. Contact Sodtrack support.	Get bookings Create booking Reschedule Booking Check Options Obtain Dates Obtain Times Projects Project Creation Create Lead Create Note Create work order Get Budget Execution Detail Approve budget execution Reject budget execution Create product Update product Product Get Full Product Unit Add New Product Unit Create acquisition Create Transaction Search Customers Get Customer Search customers (Deprecated)Get Product Units by Customer Get Bookings by Customer Get Budget Execution by Customer Create Incident Update Incident Update Component Price/Cost Start Maintenance Plan
—	Unexpected server error. Contact support if the issue persists.	Available Dates
—	Unexpected server-side error. Contact Sodtrack support.	Available Hours by Date
`Unexpected server error. Contact Sodtrack support.`	—	Upsert variants and providers

502 Bad Gateway

Code	When it happens	Endpoints
`Error in createProductUnitForCustomer: {message}`	The product module is unavailable or failed. Safe to retry.	Add New Product Unit
`Error in startMaintenancePlan: {message}`	The product module is unavailable or failed. Safe to retry.	Start Maintenance Plan

503 Service Unavailable

The service is temporarily unavailable. Retry with backoff.

Code	When it happens	Endpoints
`PRODUCT_MODULE_UNAVAILABLE`	Sodtrack's product inventory service could not be reached. Retry later.	Get Full Product Unit Get Product Units by Customer

Retries

Retry 500 and 503 with exponential backoff. Do not retry 400, 403 or 404 — the request will fail identically until the payload or configuration changes. For 401, request a fresh token and retry once.