Tenant API

Errors

Every error response documented across the Tenant API, grouped by status code. 100 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

40064 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.

40111 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.

40412 documented

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

4061 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.

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
—	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
`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_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_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`	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`	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
`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
`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
`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
`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.	Get customers
`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
`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 Create Transaction Create Incident Update Incident
—	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
—	x-api-key is missing or invalid, or the request does not originate from an authorized network.	Projects Get customers
—	Missing or invalid x-api-key.	Create work order Create product Update product
—	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
—	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 Create Transaction Create Incident Update Incident
—	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
`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
`CUSTOMER_NOT_FOUND: {customerId}`	No customer exists with that id.	Get Product Units by Customer Get Bookings 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.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 Projects Project Creation Create Lead Create Note Create work order Approve budget execution Reject budget execution Create product Update product Product Get Full Product Unit Create acquisition Create Transaction Get customers Get Product Units by Customer Get Bookings By Customer Create Incident Update Incident Update Component Price/Cost
—	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

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.