Error codes
The errors a client app can meet: on the /authorize page, at your Redirect URI when the user comes back, and from the /oauth/token and /oauth/userinfo endpoints.
The /authorize page: Invalid link
When Sentra can’t verify the app or its Redirect URI, the user is sent nowhere. Sentra shows an Invalid link page with the client_id, the redirect_uri and the error code. This stops Sentra from being used to send users to an unregistered address.
| Code | Cause | What to do |
|---|---|---|
invalid_client | The client_id is unknown. | Check SSO_APP_ID. |
invalid_redirect_uri | The redirect_uri doesn’t exactly match a registered Redirect URI. | Match the scheme, host, port, path and query, or register that URI in the console. |
application_inactive | A Sentra admin deactivated the app. | Contact a Sentra admin. |
state_required | state is empty or longer than 512 characters. | Always send a random state from your app. |
Because nothing is redirected, your app receives nothing. Only the user sees these errors, so test your sign-in link whenever you change a Redirect URI.
At your Redirect URI
Once the app and Redirect URI are verified, other errors are sent back to your Redirect URI with the same state:
https://api.belajar.contoh.id/auth/sso/callback?error=access_denied&state=r7Kx2vQ9mT4w...Check state first, as with a successful response. These errors carry no error_description.
error | When | What to do |
|---|---|---|
access_denied | The user denied access on the consent screen. | Show a message and a button to try again. |
login_required | prompt=none, but the user isn’t signed in to Sentra, their session is older than max_age, or they must change their password first. | Try again without prompt=none so the user can sign in. |
consent_required | prompt=none, but the user hasn’t consented to your app. | Try again without prompt=none so the consent screen shows. |
invalid_request | Unknown prompt value, max_age isn’t a whole number of 0 or more, code_challenge_method isn’t S256, or code_challenge isn’t 43–128 characters. | Fix the /authorize parameters. |
unsupported_response_type | response_type isn’t code. | Send response_type=code. |
Without prompt=none, Sentra returns no error in these situations: the user is asked to sign in, change their password or consent first.
POST /oauth/token
Token errors follow the OAuth 2.0 format, with a Cache-Control: no-store header:
curl -i -X POST "$SSO_API_URL/oauth/token" \
-u "$SSO_APP_ID:$SSO_CLIENT_SECRET" \
--data-urlencode grant_type=authorization_code \
--data-urlencode code=wrong-code \
--data-urlencode redirect_uri="$SSO_REDIRECT_URI"HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Cache-Control: no-store
{"error":"invalid_grant","error_description":"code is invalid"}| Status | error | error_description | Meaning and action |
|---|---|---|---|
| 400 | invalid_request | code and redirect_uri are required | code or redirect_uri is missing. |
| 400 | invalid_request | parameters must be sent in the body, not the URL | Move the parameters from the query string to the body. |
| 400 | invalid_request | use one client authentication method | Send credentials with HTTP Basic or in the body, not both. |
| 400 | invalid_request | client_id does not match the Authorization header | The client_id in the body differs from HTTP Basic. |
| 400 | unsupported_grant_type | only authorization_code is supported | Send grant_type=authorization_code. |
| 401 | invalid_client | client authentication failed | Wrong or missing App ID or Client secret, or the app is deactivated. After rotating the secret, update your .env. |
| 400 | invalid_grant | code is invalid | Unknown code, or it belongs to another app. |
| 400 | invalid_grant | code was already used | The code was already exchanged. Don’t repeat the exchange. |
| 400 | invalid_grant | code expired | More than 60 seconds passed. Exchange the code right away in the callback. |
| 400 | invalid_grant | redirect_uri does not match | Send the same redirect_uri as in /authorize. |
| 400 | invalid_grant | code_verifier is required | /authorize used PKCE; send the code_verifier. |
| 400 | invalid_grant | code_verifier does not match | The code_verifier doesn’t pair with the code_challenge. Check the value in the session. |
| 400 | invalid_grant | code_verifier sent but no code_challenge was | Send code_verifier only when /authorize used PKCE. |
| 400 | invalid_grant | user is not active | The account is deactivated in Sentra. Refuse the sign-in. |
| 429 | slow_down | too many token requests | Too many requests from your IP. Wait a moment. |
| 500 | server_error | try again later | A problem at Sentra. Try again later. |
invalid_grant, the code can’t be used any more. Send the user to sign in again from the start; don’t retry with the same code.GET /oauth/userinfo
curl -i "$SSO_API_URL/oauth/userinfo" -H "Authorization: Bearer x"HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token"
{"error":"invalid_token","error_description":"the access token is invalid or expired"}| Status | error | error_description | Meaning and action |
|---|---|---|---|
| 401 | invalid_token | missing bearer token | Send an Authorization: Bearer <token> header. |
| 401 | invalid_token | the access token is invalid or expired | The token is malformed or more than 15 minutes old. There’s no refresh token: ask the user to sign in again if you need fresh data. |
| 401 | invalid_token | the application is not active | Your app is deactivated. |
| 401 | invalid_token | the user is not active | The account is deactivated in Sentra. End the user’s session in your app. |
| 500 | server_error | try again later | A problem at Sentra. Try again later. |