Common Error Scenarios
Authentication Errors
Missing Authorization Header
Request:
curl -X GET https://sso.example.com/api/user
# Missing: -H "Authorization: Bearer {jwt}"
Response (401 Unauthorized):
{
"error": "Missing or invalid Authorization header",
"error_code": "UNAUTHORIZED",
"timestamp": "2025-01-15T10:30:00Z"
}
Solution: Include Authorization: Bearer {jwt} header in request.
Expired JWT Token
Request:
curl -X GET https://sso.example.com/api/user \
-H "Authorization: Bearer {expired_jwt}"
Response (401 Unauthorized):
{
"error": "Token expired",
"error_code": "TOKEN_EXPIRED",
"timestamp": "2025-01-15T10:30:00Z"
}
Solution: Use refresh token to get new access token:
curl -X POST https://sso.example.com/api/auth/refresh \
-H "Content-Type: application/json" \
-d '{"refresh_token": "your-refresh-token"}'
Invalid API Key
Request:
curl -X GET https://sso.example.com/api/service/users \
-H "X-API-Key: sk_invalid_key"
Response (401 Unauthorized):
{
"error": "Invalid API key",
"error_code": "UNAUTHORIZED",
"timestamp": "2025-01-15T10:30:00Z"
}
Solution: Verify API key is correct and hasn’t been revoked.
Authorization Errors
Insufficient Permissions
Request: Platform owner endpoint without platform owner role
curl -X GET https://sso.example.com/api/platform/organizations \
-H "Authorization: Bearer {non_platform_owner_jwt}"
Response (403 Forbidden):
{
"error": "Platform owner access required",
"error_code": "FORBIDDEN",
"timestamp": "2025-01-15T10:30:00Z"
}
Solution: Request platform owner access or use proper admin account.
Organization Not Active
Request: Attempting to authenticate with suspended organization
curl -X GET https://sso.example.com/auth/github?org=suspended-org&service=app
Response (403 Forbidden):
{
"error": "Organization is not active",
"error_code": "ORGANIZATION_NOT_ACTIVE",
"timestamp": "2025-01-15T10:30:00Z"
}
Solution: Contact platform administrator to reactivate organization.
Validation Errors
Missing Required Field
Request:
curl -X POST https://sso.example.com/api/service/users \
-H "X-API-Key: sk_live_abc123" \
-H "Content-Type: application/json" \
-d '{}'
Response (400 Bad Request):
{
"error": "Missing required field: email",
"error_code": "BAD_REQUEST",
"timestamp": "2025-01-15T10:30:00Z"
}
Solution: Include all required fields in request body.
Invalid Email Format
Request:
curl -X POST https://sso.example.com/api/service/users \
-H "X-API-Key: sk_live_abc123" \
-H "Content-Type: application/json" \
-d '{"email": "not-an-email"}'
Response (400 Bad Request):
{
"error": "Invalid email format",
"error_code": "BAD_REQUEST",
"timestamp": "2025-01-15T10:30:00Z"
}
Solution: Provide a valid email address.
Resource Errors
Resource Not Found
Request:
curl -X GET https://sso.example.com/api/service/users/invalid-user-id \
-H "X-API-Key: sk_live_abc123"
Response (404 Not Found):
{
"error": "User not found or has not authenticated with this service",
"error_code": "NOT_FOUND",
"timestamp": "2025-01-15T10:30:00Z"
}
Solution: Verify the resource ID and ensure user has authenticated with your service.
Resource Limit Exceeded
Request: Creating service when at tier limit
curl -X POST https://sso.example.com/api/organizations/acme-corp/services \
-H "Authorization: Bearer {jwt}" \
-d '{"name": "New Service", "slug": "new-svc"}'
Response (400 Bad Request):
{
"error": "Service limit exceeded for organization tier",
"error_code": "SERVICE_LIMIT_EXCEEDED",
"timestamp": "2025-01-15T10:30:00Z"
}
Solution: Upgrade organization tier or delete unused services.
Rate Limiting
Too Many Requests
Request: Exceeding rate limit
# 101st request within rate limit window
curl -X GET https://sso.example.com/api/service/users \
-H "X-API-Key: sk_live_abc123"
Response (429 Too Many Requests):
{
"error": "Rate limit exceeded",
"error_code": "RATE_LIMIT_EXCEEDED",
"timestamp": "2025-01-15T10:30:00Z"
}
Headers:
Retry-After: 60
Solution: Wait for rate limit reset or implement exponential backoff.
See Also: Rate Limiting Concepts for detailed rate limit policies and best practices.