Troubleshooting Platform Errors
Key Takeaways
Start with the affected tenant, user or client, affected operations, time range, and recent changes.
A gateway 401, 403, and 429 point to different checks. Read the response details and endpoint contract.
Compare public service status with tenant jobs, operator context, and source or workflow details.
After a repair, re-run the original scope and verify the actual outcome, including queued work.
Isolate the failure boundary
Collect the tenant, timestamp and time zone, actual action, actor or OAuth client, affected object, and observed error. Write down a known good comparison before making a change. Ask whether the problem affects many users and unrelated actions, one delegated user, one client, one workflow, or one source. Check the matching service and region on SailPoint Status when there is a broad or simultaneous failure. A public status page reports provider status. Tenant-specific errors, record permissions, or queued jobs can still explain a case even when the service page shows normal service.
Imagine that desktop sign-in and browsing work, but a scheduled integration starts failing. Capture the exact tenant host, API version, method and response details, and record a request identifier if one is available. Check authorization against the named endpoint. For a single user or role, reproduce with a controlled test identity that has the same effective permission and segmentation. Changing to an organization administrator can isolate a permissions difference, but an administrator's success does not establish that the user's original permission or role configuration is correct. Check user level and actual record coverage on the intended surface.
| Symptom | First comparison | Evidence that narrows the cause |
|---|---|---|
| Sign-in fails for a group using one identity profile | Same tenant with a different known working sign-in route | Profile method, SAML mapping or directory association applicable to the affected group |
| An API call returns 401 | Compare the request and authorized credentials against the endpoint documentation | Validity and expiry of the bearer token, intended host and actual header |
| An API call returns 403 after successful token issuance | Compare one allowed and one denied action with the intended actor | Endpoint flow, scopes, user level or caller context, and permitted record |
| An integration returns 429 at load | Compare concurrency across workers using that client ID and API version | Rate response, Retry-After header and applicable rate limit |
| A workflow fails for certain events | Compare affected inputs and branch execution with a good run | First step with differing input or output, platform error and effect before failure |
| A source job fails while other operations work | Compare that source to a working job and inspect its recorded activity | Aggregation task results or provisioned source/account result |
Work a burst of rate errors
Suppose multiple workers use newly issued access tokens obtained with the same client registration. Calls to one API version work during quiet periods and return 429 during bursts. One teammate suggests generating additional access tokens. The dedicated SailPoint rate-limit guide says the current API gateway default is 100 requests per client ID and API version in 10 seconds, with endpoint-specific exceptions. An older Getting Started description refers to a limit per access token. Use the dedicated current rate-limit description for the gateway and check the specific endpoint. Multiple tokens from the same client do not partition a client-based budget.
Coordinate work using that client, reduce simultaneous calls, and use any returned Retry-After value. Avoid a tight retry loop. Before repeating any write, account for whether the response arrived and whether the operation can safely be performed again. Once the system recovers, compare error counts and completed operations in the initial time band. In particular, distinguish successful retry of a transport call from completion of a separate background job the call started.
Preserve reproducing evidence
When a tenant reports a failed operation, keep the original input shape after redacting data and secrets. Match the actual failure with a small allowed comparison. For example, if an access request shows processing while a user can sign in and the API credential is valid, use the recorded account activity to identify the native step. If a configuration deployment reports Partially Complete, inspect the failed and successful objects individually. Avoid replaying an entire configuration or write solely because a summary shows an error. Check for already-applied changes first. Document what changed, why the observed evidence points to the cause, and which test repeated the original behavior after repair. For a remaining incident, provide timed, redacted evidence and identifiers to the appropriate support team.
See SailPoint's service status, authorization guidance, current rate limits, deployment activity, and provisioning activity.
Three workers share one client ID and use the same API version. The gateway returns 429 during bursts, and the endpoint has no documented exception. What addresses the documented default limit?
Issue more tokens from that client and keep the same aggregate request rate.
Coordinate the client’s aggregate traffic to the API version and honor Retry-After.
Use the OAuth secret as the resource token.
Enable a different identity profile for the integration owner.
A Configuration Hub deployment reports Partially Complete, and the new policy seems inconsistent across teams. What should the engineer check before retrying?
Only the regional status page, then repeat the full deployment if the region is healthy.
Only whether the draft was approved, then assume all objects were applied.
Whether a fresh copy of the draft immediately deletes the prior deployment.
The deployment results per object, including successful changes and the errors for failed objects.
Sections you finish are checked off in the contents.