Errors
Understanding and handling SailPoint API error responses.
API errors return standard HTTP status codes (400, 401, 403, 404, 429, 5xx) with a JSON body describing the problem for programmatic handling.
- Standard HTTP status codes
- JSON error bodies with detail
- Handle 4xx (client) vs 5xx (server) differently
- Log correlation IDs for support
The SailPoint API reports problems using standard HTTP status codes accompanied by a JSON body that describes the error, often with a trace or correlation ID. Handling these correctly, distinguishing client mistakes from server issues and retrying only what is safe, is what makes an integration robust.
The status codes that matter
| Code | Meaning | Action |
|---|---|---|
| 400 | Bad request | Fix the request |
| 401 | Unauthenticated | Refresh token |
| 403 | Forbidden | Check scopes/rights |
| 404 | Not found | Check the resource id |
| 429 | Rate limited | Back off and retry |
| 5xx | Server error | Retry with backoff |
Client versus server errors
The 4xx family means the request was wrong, fixing it requires changing your call (bad body, missing scope, wrong id). The 5xx family and 429 mean the server could not serve a valid request right now, so retrying with exponential backoff is appropriate. Blindly retrying a 400 just fails repeatedly.
Use the error body and correlation ID
The JSON body usually carries a human-readable message and a correlation/trace ID. Log that ID, it is what SailPoint support needs to trace a specific failed request, and it turns "the API failed" into a diagnosable event.
Common pitfalls
- Retrying 4xx errors that will never succeed unchanged.
- Not logging correlation IDs, making support cases hard.
- Swallowing the error body and losing the actual reason.