Troubleshoot API Integrations

Troubleshoot a PBRS integration by identifying the stage that failed: connectivity, authentication, request handling, discovery, execution, rendering, or delivery.

An HTTP success response does not necessarily mean that a report was generated or delivered. Inspect the endpoint’s response, the execution result, and the resulting output separately.

Start with a short diagnostic sequence

1. Call GET /api/Service/Ping from the PBRS server.
2. Call the same endpoint from the application’s host.
3. Obtain a fresh access token.
4. Call a protected read endpoint.
5. Retrieve the target schedule and confirm its ID and type.
6. Submit one controlled asynchronous execution.
7. Inspect its execution status and result.
8. Verify the generated file and delivery destination.

Stop at the first failing stage and investigate it before repeating later steps.

Find the relevant symptom

API connectivity

Check the service before investigating request bodies or reporting settings.

GET /api/Service/Ping

The endpoint requires no token and returns the JSON number:

1

If the request fails locally

Check:

• The PBRS API service is installed and running.
• The hostname, protocol, and port match the configured address.
• The API listener is available.
• Any configured HTTPS binding and certificate are valid.

Starting the PBRS scheduler does not start an unavailable API service.

If the request works locally but fails remotely

Check:

• DNS resolution from the application host.
• Network routing and firewall rules.
• The configured API port.
• Proxy or load-balancer routing, if used.
• Certificate trust and hostname matching for HTTPS.
• Whether an intermediary changes the request path or strips headers.

Resolve certificate or trust problems rather than disabling TLS verification.

A successful Ping confirms API connectivity. It does not verify credentials, scheduler state, database access, report rendering, or delivery.

Authentication

Use the token route that matches the credentials.

The client-credentials route is /oauth2/token, without /api.

For client credentials, supply:

• grant_type set to client_credentials.
• client_id.
• client_secret.

Send the token from either flow using:

Authorization: Bearer YOUR_ACCESS_TOKEN

Check token expiration

Tokens expire after 60 minutes. Use the returned expiration information to manage renewal and obtain a new token when needed.

Do not continue retrying with the same expired token.

If credentials are rejected

Incorrect credentials return HTTP 401. Check that:

• The credentials belong to the intended PBRS environment.
• The API client exists and its secret is current.
• The correct token route is being used.
• The request uses a supported content type.
• Values are properly encoded.
• The application extracts the correct token field.

Do not assume an authentication error always contains a JSON body.

If username/password authentication returns RequiresMfa: true, the response represents a challenge, not a completed authenticated session.

If authentication succeeds but an operation fails

Successful token acquisition does not establish permission to perform every operation.

Check the requested resource and the access requirements for the action. Some operational failures can surface as HTTP 500; inspect the available details rather than assuming every 500 is a transient server fault.

Request formatting

If a request works in Postman but fails in application code, compare the actual transmitted requests.

Use the exact property names in the request schema. The schedule identifier is uniqueid where that field is specified.

Do not wrap an entire request in a form field named model. For form requests, use the indexed field structure required by the endpoint.

Use JSON when the request needs explicit empty arrays or null values.

GET requests with bodies

Some search endpoints bind a JSON request body to GET. Some clients, API explorers, and intermediaries do not support that combination reliably.

The following searches also support POST:

POST /api/SingleSchedule/GetAll
POST /api/SingleSchedule/GetAllPaginated

Use their POST forms when your client cannot send GET bodies.

Do not assume that every GET endpoint has a POST equivalent.

Response handling

Parse each response according to its endpoint contract.

Before parsing, inspect the HTTP status, content type, and whether a body is present.

A JSON parsing exception after HTTP 200 can be a client-side handling error rather than a failed PBRS operation.

Package updates echo the submitted model. Retrieve the package separately to verify the saved configuration.

Encoded JSON fields

Some fields contain JSON inside a string.

Examples include:

• ResultJson in execution records.
• ValuesJson in data-driver requests.
• returnModel in import responses.

Parse or serialize the inner value separately. Do not treat these fields as directly nested JSON objects or arrays.

Object discovery

If a search returns no results, first confirm the environment and search criteria.

Keyword searches

Supply explicit, nonempty FilterValues.

Missing or empty filters do not mean “return everything.” They trigger a generated search value. The default LIKE comparison normally finds nothing, while negative operators can behave differently.

Check:

• The schedule’s actual keywords.
• FilterOperator.
• MatchType.
• Whether the request body reached PBRS.
• Whether the endpoint searches the intended schedule source or type.

Reporting objects

Verify the configured reporting account and its access to the workspace, report, or server.

Use discovered identifiers rather than substituting display names for IDs.

Keep these values separate:

For package execution, use the package’s ID rather than an individual member’s ID.

Create and update requests

Check the request schema for the specific report source and operation.

A create model, read response, full update model, and import payload are not interchangeable.

Full schedule updates

When updating a schedule:

• Include the existing schedule ID.
• Include the required recurrence.
• Preserve the complete intended destination collections.
• Preserve destination IDs for retained destinations.
• Preserve report filters, parameters, bookmarks, rendering, and export settings.
• Retain an authoritative source definition for settings omitted from read-back.

An omitted destination can be removed during a full update. An empty array does not mean “leave unchanged.”

Do not submit a partial full-update request to change one field.

Email recipients disappear after an update

For:

PUT /api/SingleSchedule/UpdateEmailDestination

the recipient rules are:

Omitting Cc or Bcc can clear them because they default to empty arrays.

Omitting BodyFormat can change an HTML message to text. Send null to preserve the existing format.

These rules apply to the dedicated email update endpoint, not to complete schedule definitions.

A batch request fails after creating some schedules

Earlier items can remain when a later item fails in a bulk creation request.

Before retrying:

1. Inspect the destination environment.
2. Identify which items were created.
3. Record their IDs.
4. Resolve incomplete or duplicate results.
5. Retry only the remaining work when appropriate.

Do not assume a failed batch was rolled back or that the error response contains every ID created before the failure.

An import fails

Use a compatible PBRS-exported definition. Do not substitute a schedule Get response or a normal create request.

Verify build compatibility, dependencies, accounts, folders, paths, and credentials.

Inspect the destination before retrying. Import is not guaranteed to be transactional or idempotent.

Execution

For asynchronous execution, retain the returned ExecutionId and use it to inspect status:

GET /api/Schedule/GetExecutionStatus?ExecutionId=RETURNED_EXECUTION_ID

Record the schedule ID, schedule type, submission time, and target server alongside it.

Execution remains waiting or is slow

Check:

GET /api/Service/IsSchedulerRunning
GET /api/Schedule/GetNumberOfFreeThreads
GET /api/Schedule/GetExecutionQueue
GET /api/SystemMonitor/GetCurrentlyExecuting

These endpoints answer different questions:

• Scheduler status describes scheduler state.
• Free threads describe current server capacity.
• The API queue describes waiting, executing, and retained API executions.
• The task monitor describes currently executing processes.

A capacity value of zero does not prove that the service is unhealthy. It is also not a reservation or a prediction of when capacity will become available.

For collaborative execution, verify the assigned server, connectivity, shared database access, and reporting dependencies on that server.

PBRS does not impose API throttling, but execution capacity, machine resources, and upstream service limits still constrain throughput.

Completed does not mean successful

Parse ResultJson when it is populated.

For example, this execution result is a failure:

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

Do not mark an execution successful solely because:

• The submission returned HTTP 200.
• An ExecutionId was returned.
• The status is Completed.
• A completion timestamp exists.

Inspect the application result and verify delivery as required.

Stale and timeout results

An empty result on a stale execution is not success.

Execution cleanup uses a configurable timeout whose default is 36000 seconds, or 10 hours. Cleanup can mark an overdue execution Completed with a failed result and error number 1041226.

The timeout message can refer to 10 hours even when the configured timeout differs. Do not derive the current configuration solely from the message text.

Keep these deadlines separate:

• Your HTTP request timeout.
• Your application’s polling deadline.
• PBRS execution cleanup.
• Queue record availability.

A client timeout does not cancel server-side work.

An execution record is no longer available

The API queue is not a durable history store. A missing record does not prove success, failure, or cancellation.

Use retained application records, PBRS execution history, logs, and output evidence to reconcile the outcome.

In the desktop application, open System Monitor → API Execution Queue to inspect API activity. See the API Execution Queue walkthrough.

Cancellation fails

CancelExecution uses an ExecutionId to locate and terminate its associated process. A waiting entry without a live process may not be cancellable through that path.

TerminateSchedule uses a ProcessId. It is a different operation with a different identifier.

After a cancellation attempt, inspect execution state again. Cancellation and termination do not reverse output already generated or delivered.

Rendering and data export

If the execution reaches rendering but the output is wrong, inspect the source-specific configuration.

Check:

• Reporting account access.
• Report URL, workspace, or report path.
• Parameters and filters.
• Bookmark configuration.
• Rendering method and loading times.
• Selected pages.
• Output format.
• Template paths and permissions.

Compare a controlled execution in PBRS with the API-triggered execution using the same configuration.

Pages are missing

PagesToRender uses one-based page numbers and ranges.

Examples:

{
  "PagesToRender": "1,2,5-10"
}

{
  "PagesToRender": ""
}

An empty string selects all pages. The default value is "1", so leaving the default can produce only the first page.

Power BI data-only Excel export fails

Check:

• OutputFormat is MS Excel - Data Only (*.xlsx).
• The required export settings are supplied.
• PageNumber is zero-based.
• VisualTitle matches the discovered visual title.
• ExportType is 0 for summary data or 1 for underlying data.
• The source permits the requested export.
• Template files are accessible from the executing PBRS machine.
• Worksheet and column settings match the intended output.

Do not confuse zero-based visual export PageNumber with one-based rendering PagesToRender.

Preserve template settings in your authoritative configuration because read-back can omit placement details.

Data-driver validation fails

For JSON drivers, ensure ValuesJson contains a serialized array of row objects.

For package SQL drivers:

• Use Query, not SQLQuery.
• Supply a nonempty DSN.
• Verify the DSN is available to the PBRS service.
• Check credentials and query access.
• Supply one source rather than both SQL and JSON.

Use a JSON serializer to handle escaping correctly.

Delivery

If output was generated but did not arrive, check delivery separately from rendering.

A Windows path refers to the executing PBRS machine’s environment, not the computer making the API request.

For email, CustomerSenderAddress is the custom sender field. Setting it does not grant permission to send as that address.

For packages and data-driven schedules, verify each recipient’s actual files and content. One successful delivery does not establish that the entire workload succeeded.

Retry and recovery

Choose recovery based on the operation and the evidence available.

Do not enable blanket retries for all GET requests. Scheduler controls, cloning, cancellation, and termination include state-changing GET operations.

No idempotency-key contract guarantees duplicate prevention for execution submission. Retain identifiers and reconcile uncertain outcomes before resubmitting.

Use bounded polling and an application deadline. When the deadline is reached, record the outcome as unresolved until further evidence establishes what happened.

Information to provide to Support

Prepare:

• PBRS version and API build.
• Target environment and server.
• Operation, HTTP method, and path.
• Timestamp with timezone.
• Sanitized request headers and body.
• HTTP status, response content type, and response body.
• Schedule name, type, folder, and uniqueid.
• ExecutionId, ProcessId, and server name when available.
• Relevant PBRS log excerpts.
• Expected result and actual result.
• Reproduction steps and whether the same schedule works directly in PBRS.
• Any known partial creation, rendering, or delivery.

Remove tokens, passwords, client secrets, sensitive connection details, recipient information, and confidential report data before sharing diagnostics.

Preserve the original evidence in an appropriately secured location so that troubleshooting does not erase the information needed to reconcile the outcome.