APIs & integration · Lesson

Errors

Quick answer

API errors return standard HTTP status codes (400, 401, 403, 404, 429, 5xx) with a JSON body describing the problem for programmatic handling.

Key takeaways

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.

Want to learn this properly?

Our live, instructor-led SailPoint Training covers this hands-on, with real projects and a certification path.

See the course Ask a question

Check your understanding

How are API errors returned?
- A. As standard HTTP status codes with a JSON body describing the error.
- B. Fix the request for 4xx; retry with backoff for 5xx and 429.
- C. Logging the correlation/trace ID from the error body.
Show answer
A. As standard HTTP status codes with a JSON body describing the error.
As standard HTTP status codes with a JSON body describing the error.
How differ 4xx and 5xx handling?
- A. Fix the request for 4xx; retry with backoff for 5xx and 429.
- B. As standard HTTP status codes with a JSON body describing the error.
- C. Logging the correlation/trace ID from the error body.
Show answer
A. Fix the request for 4xx; retry with backoff for 5xx and 429.
Fix the request for 4xx; retry with backoff for 5xx and 429.
What helps with support?
- A. Logging the correlation/trace ID from the error body.
- B. As standard HTTP status codes with a JSON body describing the error.
- C. Fix the request for 4xx; retry with backoff for 5xx and 429.
Show answer
A. Logging the correlation/trace ID from the error body.
Logging the correlation/trace ID from the error body.

Frequently asked questions

What does the term Errors refer to in SailPoint?

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.

What is the practical takeaway on Errors?

The 4xx family means the request was wrong, fixing it requires changing your call (bad body, missing scope, wrong id).

What is worth remembering about Errors in practice?

The 5xx family and 429 mean the server could not serve a valid request right now, so retrying with exponential backoff is appropriate.

What tends to go wrong with Errors?

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.