Skip to content
  • There are no suggestions because the search field is empty.

Troubleshoot the PBRS REST API

Separate connectivity, authentication, request-model, execution, rendering, and delivery failures.

Review status: Draft for Development and Support review. Routes and models labelled validation required must be tested against the supported PBRS build before publication.

Start with the smallest diagnostic sequence

  1. Call GET /api/service/ping from the PBRS server.
  2. Call the same endpoint from the calling system.
  3. Request a new token using the correct flow.
  4. Call a protected read-only endpoint.
  5. Resolve the target folder or schedule again.
  6. Execute a controlled schedule asynchronously.
  7. Check status and the API Execution Queue.
  8. Verify rendering and destination logs separately.

API cannot be reached

  • Confirm that the PBRS API Windows service is installed and running.
  • Confirm the server name, configured protocol, and port.
  • Check name resolution, routing, firewall rules, and any proxy or load balancer.
  • Test locally before testing remotely.

Authentication fails

  • Do not interchange the client-credentials and username/password token routes.
  • Use bearer for client-credentials tokens and token for username/password tokens.
  • Confirm application/x-www-form-urlencoded for the documented token requests.
  • Request a fresh token; the public documentation states a 24-hour lifetime.
  • Confirm that the API client still exists and its secret has not been rotated.

Postman works but application code fails

  • Compare the exact URL, leading slash, route casing, HTTP method, authorization scheme, content type, and serialized body.
  • Confirm whether the operation uses form fields, query parameters, or a nested model.
  • Check property names and casing, especially UniqueId.
  • Be aware that the current public material documents request bodies on some GET operations; some libraries and intermediaries do not handle GET bodies consistently.

Execution is queued or slow

  • Confirm that the PBRS scheduler is running.
  • Check GetNumberOfFreeThreads.
  • Inspect GetExecutionQueue and the PBRS API Execution Queue screen.
  • Test the schedule directly in PBRS.
  • Check source-system authentication and report rendering time.
  • Reduce concurrency and poll with backoff.

Execution completes but no file arrives

  • Confirm that the intended destination is enabled.
  • Verify recipients, paths, account credentials, permissions, and storage availability.
  • Check the requested format against the report type.
  • Review rendering and delivery logs.
  • Repeat with a controlled test destination.

Information to provide to Support

  • PBRS version and API build.
  • Operation and timestamp.
  • Sanitized request and response.
  • Schedule name, type, folder path, UniqueId, and ExecutionId.
  • Relevant PBRS log excerpt.
  • Steps required to reproduce the result in Postman.

Redaction: Remove passwords, access tokens, client secrets, connection strings, recipient data, and confidential report data before sharing diagnostics.

Troubleshoot by layer

Layer Typical evidence First action
Network and TLS DNS, refused/reset connection, certificate failure Test host, port, firewall and approved certificate chain
Authentication and permission Token failure, 401/403 or permission resolution error Confirm scheme, expiry, client and PBRS role
Request contract 400, binding or serialization error Compare raw request with the verified example
Scheduler and capacity Waiting or long-running execution Check service state, free threads and queue
Rendering and source Report, visual, filter or parameter failure Validate source access and rendering mode
Destination Execution completes but delivery is missing Verify artifact creation, credentials and destination response

Safe escalation bundle

Include PBRS build, timestamp and timezone, sanitized route and body, HTTP status, schedule and execution identifiers, server name, service state, queue evidence and expected versus actual result. Remove tokens, passwords, recipient data and internal stack traces.

Service running but API unresponsive

A running Windows service is not sufficient proof of API health. Test in layers:

  1. Verify the service process and registered executable path.
  2. Call /api/service/ping locally.
  3. Call ping from the approved remote integration host.
  4. Request a new token.
  5. Call a protected read operation.
  6. Run a controlled asynchronous schedule and verify delivery.

Alert on repeated synthetic-check failures even when the Windows service remains in the Running state.

Upstream Power BI account troubleshooting

  • Identify whether the source uses a user account or service principal.
  • Check for password, client-secret, tenant-policy or workspace-permission changes.
  • Refresh or revalidate the Power BI account inside PBRS.
  • Repeat account, workspace and report discovery.
  • Run the report directly in PBRS before blaming the REST request.

Common contract failures seen in Support

  • Wrong ScheduleType accepted without producing an artifact.
  • Paginated creation missing nested recurrence or destination data.
  • Weekly recurrence accepted without its day selection.
  • Postman request succeeds while application serialization changes casing, nesting, nulls or escaping.
  • API service files are missing or registered to the wrong installation path after upgrade.
  • Raw SQL or .NET exception details are exposed; redact these before escalation.

Documentation standard: Record the PBRS build used for verification, test in a non-production environment, redact credentials and customer data, and confirm the saved PBRS state after every write.