Error codes

Every error the API returns carries a stable code such as REQ001 or DATA002. The code is the part you should branch on in your integration: the human-readable message may be reworded over time, but a code, once published, never changes meaning and is never reused.

The error envelope

An error response carries the code alongside the message, plus a link to the section on this page that explains it:

{
    "Error": "Bad Request",
    "Description": "The job JOB001 was not found.",
    "Code": "DATA002",
    "Link": "https://docs.dimescheduler.com/errors/data002"
}

Code and Link are omitted when null, so an older client that does not know about them keeps working unchanged. In the .NET SDK both are exposed on FailedRequestException.

How codes are grouped

The prefix tells you which layer rejected the call, and therefore who can fix it:

Prefix	Meaning	Who resolves it
REQ	Malformed request or protocol misuse	The caller, by correcting the request
USR	Authentication failed	The caller, by correcting the credentials
PERM	Not entitled to the operation	An administrator, by granting access or licensing the module
DATA	Referenced data missing or in conflict	Usually the caller, by synchronising master data first
APP	Rejected by a business rule	The caller, by satisfying the rule
SRV	Internal failure	Dime.Scheduler support
EXT	Downstream service failed	Usually transient, retry

Retrying

SRV and EXT errors are worth retrying with a backoff. REQ, USR, PERM and APP errors will fail again in exactly the same way until the request or the configuration changes, so retrying them only adds load.

Placeholders such as {0} in the messages below are filled in with the offending value at runtime.

Request errors (REQ)

The request itself is malformed or misuses the protocol. A schema validator could reject these without knowing anything about your data.

REQ000

The request is invalid: 0

Returned with HTTP 400.

How to resolve. Correct the request and try again.

REQ001

The number of parameter names does not match the number of parameter values.

Returned with HTTP 400.

How to resolve. Send exactly one value for each parameter name.

REQ002

A required parameter is missing: 0.

Returned with HTTP 400.

How to resolve. Add the missing parameter to the request and try again.

REQ003

The action 0 does not exist.

Returned with HTTP 400.

How to resolve. Check the action name against the list of available actions.

REQ004

The parameter 0 does not exist for action 1.

Returned with HTTP 400.

How to resolve. Remove the parameter or correct its name.

REQ005

The parameter 0 has an invalid value.

Returned with HTTP 400.

How to resolve. Correct the parameter value and try again.

REQ006

The date values are out of order: 0.

Returned with HTTP 400.

How to resolve. Adjust the dates so each start precedes its corresponding end.

REQ007

The task end date cannot be scheduled without a start date or a required duration.

Returned with HTTP 400.

How to resolve. Send a start date alongside the end date, or send a required duration so the start can be derived.

Authentication errors (USR)

Dime.Scheduler could not establish who is calling.

USR001

The credentials are invalid.

Returned with HTTP 401.

How to resolve. Verify the credentials and try again.

USR002

The tenant 0 is unknown.

Returned with HTTP 401.

How to resolve. Verify the tenant identifier and try again.

USR003

The service account is registered in more than one tenant.

Returned with HTTP 403.

How to resolve. Use a dedicated service account for each tenant.

Authorization errors (PERM)

The caller is known, but is not entitled to the operation.

PERM001

The API key is not valid for this environment.

Returned with HTTP 403.

How to resolve. Verify the API key and try again.

Data errors (DATA)

The request is well formed, but the data it points at is missing or in a conflicting state.

DATA001

The requested item was not found.

Returned with HTTP 404.

How to resolve. Verify the identifier and try again.

DATA002

The job 0 was not found.

Returned with HTTP 404.

How to resolve. Verify the job number and try again.

DATA003

The task 0 was not found.

Returned with HTTP 404.

How to resolve. Verify the task number and try again.

DATA004

The resource 0 was not found.

Returned with HTTP 404.

How to resolve. Verify the resource numberResource numberThe identifier a resource carries in the back office. Time entries and other records are keyed on it, so a resource created by hand without one cannot have time registered. and try again.

DATA005

The appointment 0 was not found.

Returned with HTTP 404.

How to resolve. Verify the appointmentAppointmentA task scheduled to a resource for a specific period - the scheduled instance you see on the planning board. identifier and try again.

DATA006

The calendar 0 was not found.

Returned with HTTP 404.

How to resolve. Verify the calendarCalendarA definition of when work can happen, for the whole tenant or for specific resources: business hours, weekends and holidays. Calendars shade non-working time on the planning board and skip it in Gantt durations. code and try again.

DATA007

The filter group 0 was not found.

Returned with HTTP 404.

How to resolve. Verify the filter groupFilter groupA configurable set of fields used to filter resources and tasks on the planning board. name and try again.

DATA008

The filter value 0 was not found for filter group 1.

Returned with HTTP 404.

How to resolve. Verify the filter valueFilter valueA single value inside a filter group, used as a qualification on a resource or a requirement on a task. and try again.

DATA009

No assignment was found for resource 0 on task 1 in job 2.

Returned with HTTP 404.

How to resolve. Verify the resource, task, and job identifiers and try again.

DATA010

The statement conflicted with a foreign key constraint.

Returned with HTTP 409.

How to resolve. Import the referenced record first, or remove the reference.

DATA011

The appointment does not belong to a recurring series.

Returned with HTTP 404.

How to resolve. Verify the appointment identifier refers to a recurring appointment.

DATA012

The container 0 was not found.

Returned with HTTP 404.

How to resolve. Verify the containerContainerA grouping mechanism that bundles related tasks or appointments so planners can move and manage them together. name or identifier and try again.

DATA013

The appointment field 0 was not found.

Returned with HTTP 404.

How to resolve. Verify the field code and try again.

DATA014

Several allocations exist for resource 0 on task 1 in job 2.

Returned with HTTP 409.

How to resolve. Send the ExternalId of the allocation to address.

DATA015

Allocation 0 was not found.

Returned with HTTP 404.

How to resolve. Reload the board and try again.

Business rule errors (APP)

The request is well formed and the data exists, but a business rule rejects it. These are the errors that need domain context to understand.

APP001

Changing the task type is not possible for a task with existing appointments.

Returned with HTTP 422.

How to resolve. Remove the task's appointments before changing its type.

APP002

Resource 0 is a group and cannot be booked through the import.

Returned with HTTP 422.

How to resolve. Book an individual resource instead.

APP003

Resource 0 is not a group: its group behavior is not set.

Returned with HTTP 422.

How to resolve. Target a resource that is configured as a group.

APP004

Resource 0 cannot be a member of itself.

Returned with HTTP 422.

How to resolve. Choose a different member resource.

APP005

A crew can only contain individual resources or other crews; resource 0 is a pool or a department.

Returned with HTTP 422.

How to resolve. Add only individual resources or crewsCrewA resource that stands for a group of other resources. Dropping work on a crew fans the booking out to every member, which suits people who always work together. to a crew.

APP006

Could not acquire the membership lock for 0.

Returned with HTTP 409.

How to resolve. Retry the operation.

APP007

Adding resource 0 would create a circular membership.

Returned with HTTP 422.

How to resolve. Review the group memberships and remove the cycle.

APP008

GPS tracking is not enabled for resource 0 and GPS tracking resource 1.

Returned with HTTP 422.

How to resolve. Enable GPS trackingGPS trackingLive location tracking of mobile resources, shown on the map so planners can dispatch the nearest available person. on the resource and try again.

APP009

The record 0 cannot be deleted because it is associated with existing appointments.

Returned with HTTP 409.

How to resolve. Remove the appointments first, or retry the command with CheckAppointments set to 0.

APP010

Sending multiple values for select fields is not supported.

Returned with HTTP 422.

How to resolve. Send a single value for the select field.

APP011

UseFixPlanningQty must be true to be able to set the PlanningQty field.

Returned with HTTP 422.

How to resolve. Enable the fixed planning quantityPlanning quantityThe amount of work an appointment represents, by default its duration in hours. A conversion factor can express it in another unit, and the capacity view compares it against resource load. on the appointment before setting the planning quantity.

APP012

A task cannot depend on itself (job 0, task 1).

Returned with HTTP 422.

How to resolve. Choose a different predecessor or successor task.

APP013

A time entry cannot move from status 0 to status 1.

Returned with HTTP 422.

How to resolve. Follow the time entryTime entryA claim of a resource's time on one task for one calendar day. This is the record that is submitted to the back office, where it becomes a time sheet line. lifecycle. The import only accepts these transitions:

From	To
0 Draft	1 Submitting
1 Submitting	2 Accepted or 3 Failed
2 Accepted	0 Draft, 4 Approved or 5 Rejected
3 Failed	0 Draft or 1 Submitting
4 Approved	2 Accepted
5 Rejected	0 Draft or 1 Submitting

Anything else is refused, including jumping from Draft straight to Accepted or reopening an Approved entry. Check the status the entry is in now and send the next step instead. The statuses themselves are described on the time API page.

APP014

The time entries of resource 0 on 1 would add up to more than 24 hours.

Returned with HTTP 422.

How to resolve. Reduce the claimed time, or remove a duplicate entry, so the resource's entries for that day stay within 24 hours. Before an upsert is accepted, the duration of the new or changed entry is added to the resource's existing entries on that date. The usual causes are an entry sent twice with different identifiers, or a duration computed in the wrong unit. Moving an entry to another resource or date runs the check against the target day as well.

APP015

Time session 0 has been folded into a time entry and cannot be changed through the import.

Returned with HTTP 409.

How to resolve. Unlink the session from its time entry in Dime.Scheduler and retry, or delete the time entry, which releases its sessions again. Once a session is folded into an entry, the entry is the record of truth and the session is frozen, because changing it would silently alter the totals of an entry that may already be submitted. To correct the reported time, change the time entry rather than the session behind it.

APP016

Task 0 starts before job 1 starts.

Returned with HTTP 422.

How to resolve. Move the task start forward, or move the job start back, so the task falls inside the job.

Server errors (SRV)

A failure on our side.

SRV001

An unexpected error occurred while processing the request.

Returned with HTTP 500.

How to resolve. Try again later, and contact support if the problem persists.

External errors (EXT)

A third-party service that Dime.Scheduler depends on failed.

EXT001

A downstream service did not respond in time.

Returned with HTTP 504.

How to resolve. Try again later, and contact support if the problem persists.