Troubleshooting

Token Expired (401 Unauthorized)

Problem: Access token has expired.

Solution: Use the refresh token to obtain a new access token via POST /api/v1/auth/refresh. Implement automatic retry with the new token.

Problem: Login fails with 401.

Solution: Verify email and password. Ensure the account is not locked or disabled.

Problem: Authenticated but not permitted.

Solution: Check that the user has the required role and permission for the endpoint. Use GET /api/v1/auth/me to inspect the user's roles.

Problem: Rate limit exceeded.

Solution: Implement exponential backoff. The limit is 100 requests per minute. Reduce request frequency.

Problem: Request body or parameters fail validation.

Solution: Check the error response for field-level messages. Ensure required fields are present and correctly typed.