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.

Last updated: November 2026

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.

SymptomFirst comparisonEvidence that narrows the cause
Sign-in fails for a group using one identity profileSame tenant with a different known working sign-in routeProfile method, SAML mapping or directory association applicable to the affected group
An API call returns 401Compare the request and authorized credentials against the endpoint documentationValidity and expiry of the bearer token, intended host and actual header
An API call returns 403 after successful token issuanceCompare one allowed and one denied action with the intended actorEndpoint flow, scopes, user level or caller context, and permitted record
An integration returns 429 at loadCompare concurrency across workers using that client ID and API versionRate response, Retry-After header and applicable rate limit
A workflow fails for certain eventsCompare affected inputs and branch execution with a good runFirst step with differing input or output, platform error and effect before failure
A source job fails while other operations workCompare that source to a working job and inspect its recorded activityAggregation 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.

Test Your Knowledge

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?

A

Issue more tokens from that client and keep the same aggregate request rate.

B

Coordinate the client’s aggregate traffic to the API version and honor Retry-After.

C

Use the OAuth secret as the resource token.

D

Enable a different identity profile for the integration owner.

Test Your Knowledge

A Configuration Hub deployment reports Partially Complete, and the new policy seems inconsistent across teams. What should the engineer check before retrying?

A

Only the regional status page, then repeat the full deployment if the region is healthy.

B

Only whether the draft was approved, then assume all objects were applied.

C

Whether a fresh copy of the draft immediately deletes the prior deployment.

D

The deployment results per object, including successful changes and the errors for failed objects.

Sections you finish are checked off in the contents.