Error Codes

S-Auth returns standard OAuth2 error codes along with descriptive messages to help diagnose issues.

Error Response Format

All errors are returned as JSON:

{
  "error": "error_code",
  "error_description": "Human-readable description of the error"
}

OAuth2 Errors

Authorization Endpoint Errors

These errors are returned as query parameters when redirecting back to the client.

Error Code	Description	Common Causes
invalid_request	Missing or invalid parameter	Missing required parameter, malformed request
unauthorized_client	Client not authorized	Client doesn't exist or isn't allowed this grant type
access_denied	User denied access	User clicked "Deny" on consent screen
unsupported_response_type	Response type not supported	Using something other than code
invalid_scope	Invalid scope requested	Requesting scope not allowed for this client
server_error	Server error	Internal server error

Token Endpoint Errors

These errors are returned in the response body with appropriate HTTP status codes.

Error Code	HTTP Status	Description
invalid_request	400	Missing required parameter
invalid_client	401	Client authentication failed
invalid_grant	400	Authorization code or refresh token invalid
unauthorized_client	400	Client not authorized for grant type
unsupported_grant_type	400	Grant type not supported
invalid_scope	400	Invalid scope requested

Detailed Error Descriptions

invalid_request

The request is missing a required parameter or is malformed.

Example Response:

{
  "error": "invalid_request",
  "error_description": "Missing required parameter: redirect_uri"
}

Common Causes:

• Missing grant_type in token request
• Missing code in authorization code exchange
• Missing redirect_uri when required
• Invalid URL format

Solution: Check that all required parameters are included and properly formatted.

---

invalid_client

Client authentication failed.

Example Response:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Common Causes:

• Wrong client_id
• Wrong client_secret
• Client doesn't exist
• Malformed Authorization header

Solution: Verify your client credentials are correct and properly encoded.

---

invalid_grant

The authorization code or refresh token is invalid, expired, or already used.

Example Response:

{
  "error": "invalid_grant",
  "error_description": "Authorization code has expired"
}

Common Causes:

• Authorization code expired (10 minute lifetime)
• Authorization code already used (one-time use)
• Refresh token expired (30 day lifetime)
• Refresh token already used (rotation)
• PKCE code_verifier doesn't match challenge

Solution:

• For expired codes: Start the authorization flow again
• For used codes: Don't retry token requests
• For PKCE errors: Verify your code_verifier matches the original challenge

---

unauthorized_client

The client is not authorized for the requested operation.

Example Response:

{
  "error": "unauthorized_client",
  "error_description": "Client is not authorized to use this grant type"
}

Common Causes:

• Using client_credentials grant when not allowed
• Using refresh_token grant when not allowed
• Client is configured as public but trying to use confidential-only flow

Solution: Check your client's allowed_grants configuration in the admin dashboard.

---

access_denied

The user denied the authorization request.

Example Response (as redirect):

?error=access_denied&error_description=User%20denied%20the%20request&state=xyz

Common Causes:

• User clicked "Deny" on consent screen
• User closed the consent window
• User account is suspended

Solution: Handle this gracefully in your application - it's a normal user action.

---

unsupported_grant_type

The grant type is not supported by this server.

Example Response:

{
  "error": "unsupported_grant_type",
  "error_description": "Grant type 'password' is not supported"
}

Supported Grant Types:

• authorization_code
• client_credentials
• refresh_token

Not Supported:

• password (Resource Owner Password)
• implicit (Deprecated)

---

invalid_scope

The requested scope is invalid or not allowed for this client.

Example Response:

{
  "error": "invalid_scope",
  "error_description": "Scope 'admin' is not allowed for this client"
}

Valid Scopes:

• openid
• profile
• email

Solution: Check your client's allowed_scopes configuration.

---

HTTP Status Codes

Status	Meaning
200	Success
302	Redirect (normal for authorization endpoint)
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid credentials
403	Forbidden - Not allowed
404	Not Found - Endpoint doesn't exist
500	Server Error - Internal error
503	Service Unavailable - System degraded

Admin API Errors

401 Unauthorized

Response:

{
  "error": "unauthorized",
  "error_description": "Valid access token required"
}

Cause: Missing or invalid Bearer token.

---

403 Forbidden

Response:

{
  "error": "forbidden",
  "error_description": "Admin access required"
}

Cause: User doesn't have admin access level.

---

404 Not Found

Response:

{
  "error": "not_found",
  "error_description": "User not found"
}

Cause: The requested resource doesn't exist.

---

409 Conflict

Response:

{
  "error": "conflict",
  "error_description": "Email already exists"
}

Cause: Trying to create a duplicate resource.

---

Debugging Tips

1. Check the error_description - It usually tells you exactly what's wrong

2. Verify credentials - Most errors are credential-related:

   • client_id and client_secret match
   • Authorization header is properly Base64 encoded
   • No trailing whitespace in secrets

3. Check token expiration - Use a JWT decoder to check exp claim

4. Verify redirect_uri - Must exactly match what's registered

5. Enable logging - Check Better Stack logs for server-side details

6. Test with curl - Isolate whether the issue is in your code or the API:

   curl -X POST https://auth.sebbyk.net/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "Authorization: Basic $(echo -n 'client_id:secret' | base64)" \
     -d "grant_type=client_credentials"