Errors, Execution States, and Limits

PBRS API responses describe different stages of an operation: HTTP request handling, configuration changes, execution acceptance, execution results, and delivery.

Handle each stage separately. HTTP 200 does not necessarily mean that a schedule executed successfully or that every output reached its destination.

HTTP outcomes

The response contract depends on the endpoint.

Not every endpoint maps the same failure to the same HTTP status.

Do not classify every 500 response as transient. Likewise, do not require a JSON error body for every unsuccessful request. Hosting components and network intermediaries can also return their own responses.

Error response formats

Message errors

Some rejected requests return an object containing Message.

For example, an email destination update without its required identifier can return:

{
  "Message": "DestinationId is required for update operations"
}

Correct the request before retrying.

Exception errors

An exception response can contain:

{
  "Message": "An error has occurred.",
  "ExceptionMessage": "The requested operation could not be completed."
}

Additional fields can include:

• ExceptionType.
• StackTrace.
• InnerException.

These details are conditional. Clients must not require a stack trace, a particular exception type, or every field to be present.

Store diagnostic details securely. Avoid displaying raw exception content to end users because it can expose configuration or infrastructure information.

Empty error responses

Some authentication and permission failures return no body.

Check the HTTP status before attempting JSON parsing. An empty body must not replace the original error with an unrelated parsing exception.

Successful responses are not all JSON objects

Use the response schema for the specific operation.

A successful package update returns the submitted model. Retrieve the package separately to verify the saved configuration.

Import responses contain a string in returnModel. Depending on the imported schedule type, that string can contain a message or serialized diagnostic JSON. Parse it as nested JSON only when it is valid JSON.

Execution acceptance and execution results

The execution method determines the initial response.

An ExecutionId acknowledges submission or dispatch. A ProcessId identifies a process. Neither proves successful report delivery.

Synchronous execution result

A successful execution result has this shape:

{
  "Result": true,
  "ErrorMessage": "",
  "ErrorNumber": 0
}

A synchronous request can return HTTP 200 with Result: false. Check the result object as well as the HTTP status.

Execution identifiers

Use ExecutionId with:

GET /api/Schedule/GetExecutionStatus?ExecutionId=RETURNED_EXECUTION_ID

Do not substitute the schedule ID or process ID.

When investigating processes across servers, retain ServerName alongside ProcessId.

Execution states

Execution status is an open string field. Handle additional values without rejecting the entire response.

Do not infer successful execution from a completion timestamp alone. A zero completion timestamp can represent an unset value.

Parse ResultJson separately

Execution records contain ResultJson as a JSON-encoded string.

For example:

{
  "ExecutionId": "b2ad1236-e4f9-43d5-9593-993347fa4792",
  "uniqueid": 101,
  "Status": "Completed",
  "ResultJson": "{\"Result\":true,\"ErrorMessage\":\"\",\"ErrorNumber\":0}"
}

Parse the outer response first, then parse the nonempty ResultJson value.

The decoded result is:

{
  "Result": true,
  "ErrorMessage": "",
  "ErrorNumber": 0
}

If ResultJson is missing, empty, or cannot be parsed, do not mark the execution successful. Retain the response and investigate.

Execution error numbers

The following codes identify specific execution outcomes. They are not a complete error catalogue.

Timeout result

An execution can have Status: "Completed" with this decoded result:

{
  "Result": false,
  "ErrorMessage": "Schedule was removed from API execution queue due to exceeding the allowed timeout of 10 hours",
  "ErrorNumber": 1041226
}

The message refers to 10 hours even when the configured cleanup timeout differs. Do not derive the active timeout solely from this text.

Cancellation result

A cancelled execution can contain:

{
  "Result": false,
  "ErrorMessage": "Execution cancelled by user",
  "ErrorNumber": -102562911
}

Cancellation does not reverse files already generated or delivered.

Result types differ between endpoints

The property name Result does not imply one universal type.

In schedule history, "false" is a string. Do not evaluate it using generic string truthiness.

A null history result means no result is populated. It does not establish success or failure.

Timeouts and retention

Keep these limits separate.

There is no single timeout that applies to every stage and execution method.

Client timeouts

A client timeout or closed connection does not cancel server-side work.

After a timeout during creation, import, update, cloning, or execution submission, inspect the resulting state before retrying.

Execution cleanup

Cleanup can mark an overdue execution as completed with a failed result. The cleanup threshold does not promise that cancellation or record processing occurs at an exact wall-clock instant.

A cleanup result also does not establish that no output was delivered before the failure.

Queue retention

The completed-record selection window is not a durable-retention guarantee or a universal deletion schedule.

Store identifiers, timestamps, results, and relevant delivery evidence separately when your integration requires long-term records.

A missing queue entry does not establish whether the execution succeeded.

Capacity and request limits

PBRS does not impose API request throttling. This does not imply unlimited throughput, concurrency, queue capacity, or freedom from upstream service limits.

Execution depends on:

• Configured schedule capacity.
• CPU and memory.
• Report rendering requirements.
• Database and network performance.
• Destination availability.
• Reporting-service permissions and limits.
• Collaboration configuration.

Available schedule capacity

GET /api/Schedule/GetNumberOfFreeThreads

Example:

{
  "Result": 2
}

The endpoint reports available capacity for the current server. The default capacity is four, configuration can change it, and the result is clamped to zero.

The returned value is a snapshot, not a reservation. Other work can consume capacity before the next request.

The calculation can also trigger cleanup of old execution entries.

Schedule processes, page-renderer processes, and data-driver row threads are separate forms of concurrency. Do not use this count as a measurement of all three.

Payload and batch sizes

There is no universal maximum payload, batch size, or queue length specified for every public operation.

Follow endpoint-specific constraints and test representative workloads within your deployment. Do not interpret an unspecified maximum as unlimited capacity.

History pagination and time windows

Retrieve schedule history using:

GET /api/Scheduleinfo/getScheduleHistory?id=101&page=1&pageSize=50

Defaults are:

The response contains:

• Items.
• TotalCount.
• Page.
• PageSize.

Empty or out-of-range pages can return TotalCount: 0. Do not interpret that as proof that earlier pages contained no records.

Pagination does not provide a stable snapshot or a guaranteed tie-breaker for records with matching timestamps. Account for new history arriving during traversal.

Failed-schedule history

GetFailedSchedules uses a schedule-family selector:

GET /api/Scheduleinfo/GetFailedSchedules?id=reportid

Allowed selectors are reportid, packid, and autoid. Here, id is not a numeric schedule identifier.

Its time selection uses a calendar-day difference of at most one day, not an exact rolling 24-hour window.

Use ExecutionDateEpoch for the recorded execution time. This operation does not populate StartedAtUtc or FinishedAtUtc.

Empty search results

For keyword-based schedule searches, missing filters do not mean “list all.”

Supply explicit, nonempty FilterValues. Missing or empty filters trigger a generated search value. The default LIKE comparison normally finds nothing; negative operators can behave differently.

An empty search result should be interpreted using the request’s filter semantics, not as evidence that the environment contains no schedules.

Partial results and retries

Some operations can leave completed work behind when a later step fails.

Examples include:

• Earlier schedules created before a bulk request fails.
• Records created before an import fails.
• Files delivered before a package execution fails.
• A clone created before the client loses the response.

No whole-batch rollback or complete partial-ID response is guaranteed for bulk paginated and SSRS creation.

Before retrying, identify what already exists or was delivered.

No idempotency-key contract guarantees duplicate prevention for execution submission. A correlation value or repeated request body is not a duplicate-prevention guarantee.

Do not automatically retry every GET request. Start, stop, clone, cancellation, and termination operations include state-changing GET requests.

Cancellation and termination

CancelExecution resolves the process associated with an execution and terminates it. A waiting execution without a live associated process may fail cancellation.

After either operation, inspect execution or process state again. Neither operation recalls delivered output.

Recommended client handling

1. Record the operation, target server, timestamp, and relevant identifiers.
2. Inspect HTTP status, content type, and body presence.
3. Parse the endpoint-specific response.
4. For asynchronous work, retain ExecutionId.
5. Poll with bounded intervals and an application deadline.
6. Parse populated ResultJson separately.
7. Distinguish confirmed success, confirmed failure, and unresolved outcomes.
8. Verify delivery when the workflow requires it.
9. Reconcile uncertain or partial results before retrying.
10. Retain sanitized diagnostic evidence.

Treat an unresolved outcome as unresolved. Do not convert a missing response, empty result, unknown state, or polling timeout into success.